@nestia/fetcher 0.1.0

package/lib/Primitive.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Primitive type.
+ *
+ * `Primitive` is a type of TMP (Type Meta Programming) type who converts its argument as a
+ * primitive type.
+ *
+ * If the target argument is a built-in class who returns its origin primitive type through
+ * the `valueOf()` method like the `String` or `Number`, its return type would be the
+ * `string` or `number`.
+ *
+ * Otherwise, the target argument is a type of custom class, all of its custom method would
+ * be erased and its prototype would be changed to the primitive `object`. Therefore, return
+ * type of the TMP type finally be the primitive object.
+ *
+ * In addition, if the target argument is a type of custom class and it has a special
+ * method `toJSON()`, return type of this `Primitive` would be not `Primitive<Instance>`
+ * but `Primitive<ReturnType<Instance.toJSON>>`.
+ *
+ * Before                  | After
+ * ------------------------|----------------------------------------
+ * `Boolean`               | `boolean`
+ * `Number`                | `number`
+ * `String`                | `string`
+ * `Class`                 | `object`
+ * `Class` with `toJSON()` | `Primitive<ReturnType<Class.toJSON>>`
+ * Others                  | No change
+ *
+ * @template Instance Target argument type.
+ * @author Jenogho Nam - https://github.com/samchon
+ */
+export declare type Primitive<Instance> = _Equal<Instance, _Primitive<Instance>> extends true ? Instance : _Primitive<Instance>;
+declare type _Equal<X, Y> = X extends Y ? (Y extends X ? true : false) : false;
+declare type _Primitive<Instance> = _ValueOf<Instance> extends object ? Instance extends object ? Instance extends IJsonable<infer Raw> ? _ValueOf<Raw> extends object ? Raw extends object ? _PrimitiveObject<Raw> : never : _ValueOf<Raw> : _PrimitiveObject<Instance> : never : _ValueOf<Instance>;
+declare type _PrimitiveObject<Instance extends object> = Instance extends Array<infer T> ? _Primitive<T>[] : {
+    [P in keyof Instance]: Instance[P] extends Function ? never : _Primitive<Instance[P]>;
+};
+declare type _ValueOf<Instance> = _IsValueOf<Instance, Boolean> extends true ? boolean : _IsValueOf<Instance, Number> extends true ? number : _IsValueOf<Instance, String> extends true ? string : Instance;
+declare type _IsValueOf<Instance, Object extends IValueOf<any>> = Instance extends Object ? Object extends IValueOf<infer Primitive> ? Instance extends Primitive ? false : true : false : false;
+interface IValueOf<T> {
+    valueOf(): T;
+}
+interface IJsonable<T> {
+    toJSON(): T;
+}
+export {};

package/lib/Primitive.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=Primitive.js.map

package/lib/Primitive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Primitive.js","sourceRoot":"","sources":["../src/Primitive.ts"],"names":[],"mappings":""}

package/lib/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./IConnection";
+export * from "./IEncryptionPassword";
+export * from "./Primitive";
+export * from "./AesPkcs5";
+export * from "./Fetcher";
+export * from "./HttpError";

package/lib/index.js

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./IConnection"), exports);
+__exportStar(require("./IEncryptionPassword"), exports);
+__exportStar(require("./Primitive"), exports);
+__exportStar(require("./AesPkcs5"), exports);
+__exportStar(require("./Fetcher"), exports);
+__exportStar(require("./HttpError"), exports);
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,gDAA8B;AAC9B,wDAAsC;AACtC,8CAA4B;AAE5B,6CAA2B;AAC3B,4CAA0B;AAC1B,8CAA4B"}

package/lib/internal/Singleton.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/internal/Singleton.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Singleton = void 0;
+/**
+ * @internal
+ */
+var Singleton = /** @class */ (function () {
+    function Singleton(closure_) {
+        this.closure_ = closure_;
+        this.value_ = NOT_MOUNTED_YET;
+    }
+    Singleton.prototype.get = function () {
+        if (this.value_ === NOT_MOUNTED_YET)
+            this.value_ = this.closure_();
+        return this.value_;
+    };
+    return Singleton;
+}());
+exports.Singleton = Singleton;
+/**
+ * @internal
+ */
+var NOT_MOUNTED_YET = {};
+//# sourceMappingURL=Singleton.js.map

package/lib/internal/Singleton.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Singleton.js","sourceRoot":"","sources":["../../src/internal/Singleton.ts"],"names":[],"mappings":";;;AAAA;;GAEG;AACH;IAGI,mBAAoC,QAAiB;QAAjB,aAAQ,GAAR,QAAQ,CAAS;QACjD,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC;IAClC,CAAC;IAEM,uBAAG,GAAV;QACI,IAAI,IAAI,CAAC,MAAM,KAAK,eAAe;YAAE,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;QACnE,OAAO,IAAI,CAAC,MAAW,CAAC;IAC5B,CAAC;IACL,gBAAC;AAAD,CAAC,AAXD,IAWC;AAXY,8BAAS;AAatB;;GAEG;AACH,IAAM,eAAe,GAAG,EAAE,CAAC"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@nestia/fetcher",
+  "version": "0.1.0",
+  "description": "Fetcher library of Nestia SDK",
+  "main": "lib/index.js",
+  "typings": "lib/index.d.ts",
+  "scripts": {
+    "build": "rimraf lib && tsc",
+    "dev": "npm run build -- --watch",
+    "eslint": "eslint src",
+    "eslint:fix": "eslint src --fix",
+    "prettier": "prettier src --write"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/samchon/nestia"
+  },
+  "keywords": [
+    "nestia",
+    "fetcher",
+    "sdk"
+  ],
+  "author": "Jeongho Nam",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/samchon/nestia/issues"
+  },
+  "homepage": "https://github.com/samchon/nestia/packages/fetcher",
+  "devDependencies": {
+    "@types/node": "^18.11.14",
+    "@typescript-eslint/eslint-plugin": "^5.46.1",
+    "@typescript-eslint/parser": "^5.46.1",
+    "prettier": "^2.8.1",
+    "rimraf": "^3.0.2",
+    "typescript": "^4.9.4"
+  },
+  "dependencies": {
+    "import2": "^1.0.3",
+    "node-fetch": "^3.3.0"
+  },
+  "files": [
+    "README.md",
+    "LICENSE",
+    "package.json",
+    "lib",
+    "src"
+  ]
+}

package/src/AesPkcs5.ts

@@ -0,0 +1,51 @@
+import crypto from "crypto";
+
+/**
+ * Utility class for the AES-128/256 encryption.
+ *
+ *   - AES-128/256
+ *   - CBC mode
+ *   - PKCS#5 Padding
+ *   - Base64 Encoding
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export namespace AesPkcs5 {
+    /**
+     * Encrypt data
+     *
+     * @param data Target data
+     * @param key Key value of the encryption.
+     * @param iv Initializer Vector for the encryption
+     * @return Encrypted data
+     */
+    export function encrypt(data: string, key: string, iv: string): string {
+        const bytes: number = key.length * 8;
+        const cipher: crypto.Cipher = crypto.createCipheriv(
+            `AES-${bytes}-CBC`,
+            key,
+            iv,
+        );
+
+        return cipher.update(data, "utf8", "base64") + cipher.final("base64");
+    }
+
+    /**
+     * Decrypt data.
+     *
+     * @param data Target data
+     * @param key Key value of the decryption.
+     * @param iv Initializer Vector for the decryption
+     * @return Decrypted data.
+     */
+    export function decrypt(data: string, key: string, iv: string): string {
+        const bytes: number = key.length * 8;
+        const decipher: crypto.Decipher = crypto.createDecipheriv(
+            `AES-${bytes}-CBC`,
+            key,
+            iv,
+        );
+
+        return decipher.update(data, "base64", "utf8") + decipher.final("utf8");
+    }
+}

package/src/Fetcher.ts

@@ -0,0 +1,241 @@
+import import2 from "import2";
+
+import { IConnection } from "./IConnection";
+import { IEncryptionPassword } from "./IEncryptionPassword";
+import { Primitive } from "./Primitive";
+
+import { AesPkcs5 } from "./AesPkcs5";
+import { HttpError } from "./HttpError";
+import { Singleton } from "./internal/Singleton";
+
+/**
+ * Fetcher, utility class for the [**Nestia**](https://github.com/samchon/nestia) fetch.
+ *
+ * `Fetcher` is a utility class providing the {@link Fetcher.fetch} functions who're being
+ * used by all of the SDK libraries, interacting with the remote HTTP servers, who are
+ * generated by the [**Nestia**](https://github.com/samchon/nestia).
+ *
+ * As this `Fetcher` be used only by the [**Nestia**](https://github.com/samchon/nestia)
+ * generated SDK libraries, you don't need to handle this class directly. It may only be
+ * appeared in the source codes of the [**Nestia**](https://github.com/samchon/nestia)
+ * generated SDK libraries.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export class Fetcher {
+    /**
+     * Fetch function for the `GET` or `DELETE` methods.
+     *
+     * @param connection Connection information for the remote HTTP server
+     * @param encrypted Whether the request/response body be encrypted or not
+     * @param method Method of the HTTP request
+     * @param path Path of the HTTP request
+     * @return Response body data from the remote HTTP server
+     */
+    public static fetch<Output>(
+        connection: IConnection,
+        encrypted: Fetcher.IEncrypted,
+        method: "GET" | "DELETE",
+        path: string,
+    ): Promise<Primitive<Output>>;
+
+    /**
+     * Fetch function for the `POST`, `PUT` and `PATCH` methods.
+     *
+     * @param connection Connection information for the remote HTTP server
+     * @param encrypted Whether the request/response body be encrypted or not
+     * @param method Method of the HTTP request
+     * @param path Path of the HTTP request
+     * @param input Request body data for the HTTP request
+     * @param stringify JSON string conversion function, default is the `JSON.stringify`
+     * @return Response body data from the remote HTTP server
+     */
+    public static fetch<Input, Output>(
+        connection: IConnection,
+        encrypted: Fetcher.IEncrypted,
+        method: "POST" | "PUT" | "PATCH",
+        path: string,
+        input: Input,
+        stringify?: (input: Input) => string,
+    ): Promise<Primitive<Output>>;
+
+    public static async fetch<Output>(
+        connection: IConnection,
+        encrypted: Fetcher.IEncrypted,
+        method: "GET" | "DELETE" | "POST" | "PUT" | "PATCH",
+        path: string,
+        input?: object,
+        stringify?: (input: object) => string,
+    ): Promise<Primitive<Output>> {
+        if (encrypted.request === true || encrypted.response === true)
+            if (connection.encryption === undefined)
+                throw new Error(
+                    "Error on nestia.Fetcher.encrypt(): the encryption password has not been configured.",
+                );
+
+        //----
+        // REQUEST MESSSAGE
+        //----
+        // METHOD & HEADERS
+        const init: RequestInit = {
+            method,
+            headers:
+                encrypted.request === false &&
+                input !== undefined &&
+                typeof input === "object"
+                    ? {
+                          ...connection.headers,
+                          "Content-Type": "application/json",
+                      }
+                    : connection.headers,
+        };
+
+        // REQUEST BODY (WITH ENCRYPTION)
+        if (input !== undefined) {
+            let body: string = (stringify || JSON.stringify)(input);
+            if (encrypted.request === true) {
+                const headers: Singleton<Record<string, string>> =
+                    new Singleton(() => init.headers as Record<string, string>);
+                const password:
+                    | IEncryptionPassword
+                    | IEncryptionPassword.Closure =
+                    connection.encryption instanceof Function
+                        ? connection.encryption!(
+                              { headers: headers.get(), body },
+                              true,
+                          )
+                        : connection.encryption!;
+                if (is_disabled(password, headers, body, true) === false)
+                    body = AesPkcs5.encrypt(body, password.key, password.iv);
+            }
+            init.body = body;
+        }
+
+        //----
+        // RESPONSE MESSAGE
+        //----
+        // URL SPECIFICATION
+        if (
+            connection.host[connection.host.length - 1] !== "/" &&
+            path[0] !== "/"
+        )
+            path = "/" + path;
+
+        const url: URL = new URL(`${connection.host}${path}`);
+
+        // DO FETCH
+        const response: Response = await (await polyfill.get())(url.href, init);
+        let body: string = await response.text();
+        if (!body) return undefined!;
+
+        // CHECK THE STATUS CODE
+        if (response.status !== 200 && response.status !== 201)
+            throw new HttpError(method, path, response.status, body);
+
+        // FINALIZATION (WITH DECODING)
+        if (encrypted.response === true) {
+            const headers: Singleton<Record<string, string>> = new Singleton(
+                () => headers_to_object(response.headers),
+            );
+            const password: IEncryptionPassword | IEncryptionPassword.Closure =
+                connection.encryption instanceof Function
+                    ? connection.encryption!(
+                          { headers: headers.get(), body },
+                          false,
+                      )
+                    : connection.encryption!;
+            if (is_disabled(password, headers, body, false) === false)
+                body = AesPkcs5.decrypt(body, password.key, password.iv);
+        }
+
+        //----
+        // OUTPUT
+        //----
+        let ret: { __set_headers__: Record<string, any> } & Primitive<Output> =
+            body as any;
+        try {
+            // PARSE RESPONSE BODY
+            ret = JSON.parse(ret as any);
+
+            // FIND __SET_HEADERS__ FIELD
+            if (
+                ret.__set_headers__ !== undefined &&
+                typeof ret.__set_headers__ === "object"
+            ) {
+                if (connection.headers === undefined) connection.headers = {};
+                Object.assign(connection.headers, ret.__set_headers__);
+            }
+        } catch {}
+
+        // RETURNS
+        return ret;
+    }
+}
+
+export namespace Fetcher {
+    /**
+     * Whether be encrypted or not.
+     *
+     * `Fetcher.IEncrypted` is a type of interface who represents whether the HTTP request
+     * and response body must be encrypted or not.
+     *
+     * Like the {@link Fetcher} who are being used by all of the SDK libraries that are
+     * generated by the [Nestia](https://github.com/samchon/nestia), this `IEncrypted`
+     * interface would be used by the [Nestia](https://github.com/samchon/nestia) generated
+     * SDK libaries.
+     *
+     * As this `Fetcher` be used only by the [**Nestia**](https://github.com/samchon/nestia)
+     * generated SDK libraries, you don't need to handle this class directly. It may only be
+     * appeared in the source codes of the [**Nestia**](https://github.com/samchon/nestia)
+     * generated SDK libraries.
+     */
+    export interface IEncrypted {
+        /**
+         * Whether the request body be encrypted or not.
+         */
+        request?: boolean;
+
+        /**
+         * Whether the response body be encrypted or not.
+         */
+        response: boolean;
+    }
+}
+
+const polyfill = new Singleton(async (): Promise<typeof fetch> => {
+    if (
+        typeof global === "object" &&
+        typeof global.process === "object" &&
+        typeof global.process.versions === "object" &&
+        typeof global.process.versions.node !== undefined
+    ) {
+        if (global.fetch === undefined)
+            global.fetch = ((await import2("node-fetch")) as any).default;
+        return (global as any).fetch;
+    }
+    return window.fetch;
+});
+
+function is_disabled(
+    password: IEncryptionPassword,
+    headers: Singleton<Record<string, string>>,
+    body: string,
+    encoded: boolean,
+): boolean {
+    if (password.disabled === undefined) return false;
+    if (typeof password.disabled === "function")
+        return password.disabled(
+            {
+                headers: headers.get(),
+                body,
+            },
+            encoded,
+        );
+    return password.disabled;
+}
+
+function headers_to_object(headers: Headers): Record<string, string> {
+    const output: Record<string, string> = {};
+    headers.forEach((value, key) => (output[key] = value));
+    return output;
+}

package/src/HttpError.ts

@@ -0,0 +1,30 @@
+/**
+ * HTTP Error.
+ *
+ * `HttpError` is a type of error class who've been thrown by the remote HTTP server.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export class HttpError extends Error {
+    /**
+     * Initializer Constructor.
+     *
+     * @param method Method of the HTTP request.
+     * @param path Path of the HTTP request.
+     * @param status Status code from the remote HTTP server.
+     * @param message Error message from the remote HTTP server.
+     */
+    public constructor(
+        public readonly method: "GET" | "DELETE" | "POST" | "PUT" | "PATCH",
+        public readonly path: string,
+        public readonly status: number,
+        message: string,
+    ) {
+        super(message);
+
+        // INHERITANCE POLYFILL
+        const proto: HttpError = new.target.prototype;
+        if (Object.setPrototypeOf) Object.setPrototypeOf(this, proto);
+        else (this as any).__proto__ = proto;
+    }
+}

package/src/IConnection.ts

@@ -0,0 +1,32 @@
+import { IEncryptionPassword } from "./IEncryptionPassword";
+
+/**
+ * Connection information.
+ *
+ * `IConnection` is a type of interface who represents connection information of the remote
+ * HTTP server. You can target the remote HTTP server by wring the {@link IConnection.host}
+ * variable down. Also, you can configure special header values by specializing the
+ * {@link IConnection.headers} variable.
+ *
+ * If the remote HTTP server encrypts or decrypts its body data through the AES-128/256
+ * algorithm, specify the {@link IConnection.encryption} with {@link IEncryptionPassword}
+ * or {@link IEncryptionPassword.Closure} variable.
+ *
+ * @author Jenogho Nam - https://github.com/samchon
+ */
+export interface IConnection {
+    /**
+     * Host address of the remote HTTP server.
+     */
+    host: string;
+
+    /**
+     * Header values delivered to the remote HTTP server.
+     */
+    headers?: Record<string, string>;
+
+    /**
+     * Encryption password of its closure function.
+     */
+    encryption?: IEncryptionPassword | IEncryptionPassword.Closure;
+}

package/src/IEncryptionPassword.ts

@@ -0,0 +1,64 @@
+/**
+ * Encryption password.
+ *
+ * `IEncryptionPassword` is a type of interface who represents encryption password used by
+ * the {@link Fetcher} with AES-128/256 algorithm. If your encryption password is not fixed
+ * but changes according to the input content, you can utilize the
+ * {@link IEncryptionPassword.Closure} function type.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export interface IEncryptionPassword {
+    /**
+     * Secret key.
+     */
+    key: string;
+
+    /**
+     * Initialization vector.
+     */
+    iv: string;
+
+    /**
+     * Disable encryption to let content as plain.
+     *
+     * When you configure this `disabled` variable to be `false`, encryption and decryption
+     * algorithm would be disabled. Therefore, content like request or response body
+     * would be considered as a plain text instead.
+     *
+     * Default is `false`.
+     */
+    disabled?:
+        | boolean
+        | ((
+              param: IEncryptionPassword.IParameter,
+              encoded: boolean,
+          ) => boolean);
+}
+export namespace IEncryptionPassword {
+    /**
+     * Type of a closure function returning the {@link IEncryptionPassword} object.
+     *
+     * `IEncryptionPassword.Closure` is a type of closure function who are returning the
+     * {@link IEncryptionPassword} object. It would be used when your encryption password
+     * be changed according to the input content.
+     */
+    export interface Closure {
+        /**
+         * Encryption password getter.
+         *
+         * @param param Request or response headers and body content
+         * @param encoded Be encoded or to be decoded
+         * @returns Encryption password
+         */
+        (param: IParameter, encoded: boolean): IEncryptionPassword;
+    }
+
+    /**
+     * Parameter for the closure.
+     */
+    export interface IParameter {
+        headers: Record<string, string>;
+        body: string;
+    }
+}

package/src/Primitive.ts

@@ -0,0 +1,85 @@
+/**
+ * Primitive type.
+ *
+ * `Primitive` is a type of TMP (Type Meta Programming) type who converts its argument as a
+ * primitive type.
+ *
+ * If the target argument is a built-in class who returns its origin primitive type through
+ * the `valueOf()` method like the `String` or `Number`, its return type would be the
+ * `string` or `number`.
+ *
+ * Otherwise, the target argument is a type of custom class, all of its custom method would
+ * be erased and its prototype would be changed to the primitive `object`. Therefore, return
+ * type of the TMP type finally be the primitive object.
+ *
+ * In addition, if the target argument is a type of custom class and it has a special
+ * method `toJSON()`, return type of this `Primitive` would be not `Primitive<Instance>`
+ * but `Primitive<ReturnType<Instance.toJSON>>`.
+ *
+ * Before                  | After
+ * ------------------------|----------------------------------------
+ * `Boolean`               | `boolean`
+ * `Number`                | `number`
+ * `String`                | `string`
+ * `Class`                 | `object`
+ * `Class` with `toJSON()` | `Primitive<ReturnType<Class.toJSON>>`
+ * Others                  | No change
+ *
+ * @template Instance Target argument type.
+ * @author Jenogho Nam - https://github.com/samchon
+ */
+export type Primitive<Instance> = _Equal<
+    Instance,
+    _Primitive<Instance>
+> extends true
+    ? Instance
+    : _Primitive<Instance>;
+
+type _Equal<X, Y> = X extends Y ? (Y extends X ? true : false) : false;
+
+type _Primitive<Instance> = _ValueOf<Instance> extends object
+    ? Instance extends object
+        ? Instance extends IJsonable<infer Raw>
+            ? _ValueOf<Raw> extends object
+                ? Raw extends object
+                    ? _PrimitiveObject<Raw> // object would be primitified
+                    : never // cannot be
+                : _ValueOf<Raw> // atomic value
+            : _PrimitiveObject<Instance> // object would be primitified
+        : never // cannot be
+    : _ValueOf<Instance>;
+
+type _PrimitiveObject<Instance extends object> = Instance extends Array<infer T>
+    ? _Primitive<T>[]
+    : {
+          [P in keyof Instance]: Instance[P] extends Function
+              ? never
+              : _Primitive<Instance[P]>;
+      };
+
+type _ValueOf<Instance> = _IsValueOf<Instance, Boolean> extends true
+    ? boolean
+    : _IsValueOf<Instance, Number> extends true
+    ? number
+    : _IsValueOf<Instance, String> extends true
+    ? string
+    : Instance;
+
+type _IsValueOf<
+    Instance,
+    Object extends IValueOf<any>,
+> = Instance extends Object
+    ? Object extends IValueOf<infer Primitive>
+        ? Instance extends Primitive
+            ? false
+            : true // not Primitive, but Object
+        : false // cannot be
+    : false;
+
+interface IValueOf<T> {
+    valueOf(): T;
+}
+
+interface IJsonable<T> {
+    toJSON(): T;
+}