@marianmeres/http-utils 1.1.0 → 1.2.0

package/dist/index.js

@@ -0,0 +1,335 @@
+import { dset } from 'dset/merge';
+
+class HTTP_STATUS {
+    // 1xx
+    // prettier-ignore
+    static INFO = {
+        CONTINUE: { CODE: 100, TEXT: 'Continue' },
+        SWITCHING_PROTOCOLS: { CODE: 101, TEXT: 'Switching Protocols' },
+        PROCESSING: { CODE: 102, TEXT: 'Processing' },
+        EARLY_HINTS: { CODE: 103, TEXT: 'Early Hints' },
+    };
+    // 2xx
+    // prettier-ignore
+    static SUCCESS = {
+        OK: { CODE: 200, TEXT: 'OK' },
+        NON_AUTHORITATIVE_INFO: { CODE: 203, TEXT: 'Non-Authoritative Information' },
+        ACCEPTED: { CODE: 202, TEXT: 'Accepted' },
+        NO_CONTENT: { CODE: 204, TEXT: 'No Content' },
+        RESET_CONTENT: { CODE: 205, TEXT: 'Reset Content' },
+        PARTIAL_CONTENT: { CODE: 206, TEXT: 'Partial Content' },
+        MULTI_STATUS: { CODE: 207, TEXT: 'Multi-Status' },
+        ALREADY_REPORTED: { CODE: 208, TEXT: 'Already Reported' },
+        IM_USED: { CODE: 226, TEXT: 'IM Used' }, // ?
+    };
+    // 3xx
+    // prettier-ignore
+    static REDIRECT = {
+        MUTLIPLE_CHOICES: { CODE: 300, TEXT: 'Multiple Choices' },
+        MOVED_PERMANENTLY: { CODE: 301, TEXT: 'Moved Permanently' },
+        FOUND: { CODE: 302, TEXT: 'Found' },
+        SEE_OTHER: { CODE: 303, TEXT: 'See Other' },
+        NOT_MODIFIED: { CODE: 304, TEXT: 'Not Modified' },
+        TEMPORARY_REDIRECT: { CODE: 307, TEXT: 'Temporary Redirect' },
+        PERMANENT_REDIRECT: { CODE: 308, TEXT: 'Permanent Redirect' },
+    };
+    // 4xx
+    // prettier-ignore
+    static ERROR_CLIENT = {
+        BAD_REQUEST: { CODE: 400, TEXT: 'Bad Request' },
+        UNAUTHORIZED: { CODE: 401, TEXT: 'Unauthorized' },
+        PAYMENT_REQUIRED_EXPERIMENTAL: { CODE: 402, TEXT: 'Payment Required Experimental' },
+        FORBIDDEN: { CODE: 403, TEXT: 'Forbidden' },
+        NOT_FOUND: { CODE: 404, TEXT: 'Not Found' },
+        METHOD_NOT_ALLOWED: { CODE: 405, TEXT: 'Method Not Allowed' },
+        NOT_ACCEPTABLE: { CODE: 406, TEXT: 'Not Acceptable' },
+        PROXY_AUTHENTICATION_REQUIRED: { CODE: 407, TEXT: 'Proxy Authentication Required' },
+        REQUEST_TIMEOUT: { CODE: 408, TEXT: 'Request Timeout' },
+        CONFLICT: { CODE: 409, TEXT: 'Conflict' },
+        GONE: { CODE: 410, TEXT: 'Gone' },
+        LENGTH_REQUIRED: { CODE: 411, TEXT: 'Length Required' },
+        PRECONDITION_FAILED: { CODE: 412, TEXT: 'Precondition Failed' },
+        PAYLOAD_TOO_LARGE: { CODE: 413, TEXT: 'Payload Too Large' },
+        URI_TOO_LONG: { CODE: 414, TEXT: 'URI Too Long' },
+        UNSUPPORTED_MEDIA_TYPE: { CODE: 415, TEXT: 'Unsupported Media Type' },
+        RANGE_NOT_SATISFIABLE: { CODE: 416, TEXT: 'Range Not Satisfiable' },
+        EXPECTATION_FAILED: { CODE: 417, TEXT: 'Expectation Failed' },
+        IM_A_TEAPOT: { CODE: 418, TEXT: "I'm a teapot" },
+        MISDIRECTED_REQUEST: { CODE: 421, TEXT: 'Misdirected Request' },
+        UNPROCESSABLE_CONTENT: { CODE: 422, TEXT: 'Unprocessable Content' },
+        LOCKED: { CODE: 423, TEXT: 'Locked' },
+        FAILED_DEPENDENCY: { CODE: 424, TEXT: 'Failed Dependency' },
+        TOO_EARLY_EXPERIMENTAL: { CODE: 425, TEXT: 'Too Early Experimental' },
+        UPGRADE_REQUIRED: { CODE: 426, TEXT: 'Upgrade Required' },
+        PRECONDITION_REQUIRED: { CODE: 428, TEXT: 'Precondition Required' },
+        TOO_MANY_REQUESTS: { CODE: 429, TEXT: 'Too Many Requests' },
+        REQUEST_HEADER_FIELDS_TOO_LARGE: { CODE: 431, TEXT: 'Request Header Fields Too Large' },
+        UNAVAILABLE_FOR_LEGAL_REASONS: { CODE: 451, TEXT: 'Unavailable For Legal Reasons' },
+    };
+    // 5xx
+    // prettier-ignore
+    static ERROR_SERVER = {
+        INTERNAL_SERVER_ERROR: { CODE: 500, TEXT: 'Internal Server Error' },
+        NOT_IMPLEMENTED: { CODE: 501, TEXT: 'Not Implemented' },
+        BAD_GATEWAY: { CODE: 502, TEXT: 'Bad Gateway' },
+        SERVICE_UNAVAILABLE: { CODE: 503, TEXT: 'Service Unavailable' },
+        GATEWAY_TIMEOUT: { CODE: 504, TEXT: 'Gateway Timeout' },
+        HTTP_VERSION_NOT_SUPPORTED: { CODE: 505, TEXT: 'HTTP Version Not Supported' },
+        VARIANT_ALSO_NEGOTIATES: { CODE: 506, TEXT: 'Variant Also Negotiates' },
+        INSUFFICIENT_STORAGE: { CODE: 507, TEXT: 'Insufficient Storage' },
+        LOOP_DETECTED: { CODE: 508, TEXT: 'Loop Detected' },
+        NOT_EXTENDED: { CODE: 510, TEXT: 'Not Extended' },
+        NETWORK_AUTH_REQUIRED: { CODE: 511, TEXT: 'Network Authentication Required' },
+    };
+    //
+    static findByCode(code) {
+        const keys = [
+            'INFO',
+            'SUCCESS',
+            'REDIRECT',
+            'ERROR_CLIENT',
+            'ERROR_SERVER',
+        ];
+        for (const _TYPE of keys) {
+            for (const [_KEY, data] of Object.entries(HTTP_STATUS[_TYPE])) {
+                if (data.CODE == code) {
+                    return { ...data, _TYPE, _KEY };
+                }
+            }
+        }
+        return null;
+    }
+}
+
+// opinionated base for all
+class HttpError extends Error {
+    name = 'HttpError';
+    status = HTTP_STATUS.ERROR_SERVER.INTERNAL_SERVER_ERROR.CODE;
+    statusText = HTTP_STATUS.ERROR_SERVER.INTERNAL_SERVER_ERROR.TEXT;
+    body = null;
+}
+// some more specific instances of the well known ones...
+// client
+class BadRequest extends HttpError {
+    name = 'HttpBadRequestError';
+    status = HTTP_STATUS.ERROR_CLIENT.BAD_REQUEST.CODE;
+    statusText = HTTP_STATUS.ERROR_CLIENT.BAD_REQUEST.TEXT;
+}
+class Unauthorized extends HttpError {
+    name = 'HttpUnauthorizedError';
+    status = HTTP_STATUS.ERROR_CLIENT.UNAUTHORIZED.CODE;
+    statusText = HTTP_STATUS.ERROR_CLIENT.UNAUTHORIZED.TEXT;
+}
+class Forbidden extends HttpError {
+    name = 'HttpForbiddenError';
+    status = HTTP_STATUS.ERROR_CLIENT.FORBIDDEN.CODE;
+    statusText = HTTP_STATUS.ERROR_CLIENT.FORBIDDEN.TEXT;
+}
+class NotFound extends HttpError {
+    name = 'HttpNotFoundError';
+    status = HTTP_STATUS.ERROR_CLIENT.NOT_FOUND.CODE;
+    statusText = HTTP_STATUS.ERROR_CLIENT.NOT_FOUND.TEXT;
+}
+class MethodNotAllowed extends HttpError {
+    name = 'HttpMethodNotAllowedError';
+    status = HTTP_STATUS.ERROR_CLIENT.METHOD_NOT_ALLOWED.CODE;
+    statusText = HTTP_STATUS.ERROR_CLIENT.METHOD_NOT_ALLOWED.TEXT;
+}
+class RequestTimeout extends HttpError {
+    name = 'HttpRequestTimeoutError';
+    status = HTTP_STATUS.ERROR_CLIENT.REQUEST_TIMEOUT.CODE;
+    statusText = HTTP_STATUS.ERROR_CLIENT.REQUEST_TIMEOUT.TEXT;
+}
+class Conflict extends HttpError {
+    name = 'HttpConflictError';
+    status = HTTP_STATUS.ERROR_CLIENT.CONFLICT.CODE;
+    statusText = HTTP_STATUS.ERROR_CLIENT.CONFLICT.TEXT;
+}
+class Gone extends HttpError {
+    name = 'HttpGoneError';
+    status = HTTP_STATUS.ERROR_CLIENT.GONE.CODE;
+    statusText = HTTP_STATUS.ERROR_CLIENT.GONE.TEXT;
+}
+class ImATeapot extends HttpError {
+    name = 'HttpImATeapotError';
+    status = HTTP_STATUS.ERROR_CLIENT.IM_A_TEAPOT.CODE;
+    statusText = HTTP_STATUS.ERROR_CLIENT.IM_A_TEAPOT.TEXT;
+}
+// server
+class InternalServerError extends HttpError {
+    name = 'HttpInternalServerError';
+}
+class NotImplemented extends HttpError {
+    name = 'HttpServiceUnavailableError';
+    status = HTTP_STATUS.ERROR_SERVER.NOT_IMPLEMENTED.CODE;
+    statusText = HTTP_STATUS.ERROR_SERVER.NOT_IMPLEMENTED.TEXT;
+}
+class BadGateway extends HttpError {
+    name = 'HttpBadGatewayError';
+    status = HTTP_STATUS.ERROR_SERVER.BAD_GATEWAY.CODE;
+    statusText = HTTP_STATUS.ERROR_SERVER.BAD_GATEWAY.TEXT;
+}
+class ServiceUnavailable extends HttpError {
+    name = 'HttpServiceUnavailableError';
+    status = HTTP_STATUS.ERROR_SERVER.SERVICE_UNAVAILABLE.CODE;
+    statusText = HTTP_STATUS.ERROR_SERVER.SERVICE_UNAVAILABLE.TEXT;
+}
+//
+const HTTP_ERROR = {
+    // base
+    HttpError,
+    // client
+    BadRequest,
+    Unauthorized,
+    Forbidden,
+    NotFound,
+    MethodNotAllowed,
+    RequestTimeout,
+    Conflict,
+    Gone,
+    ImATeapot,
+    // server
+    InternalServerError,
+    NotImplemented,
+    BadGateway,
+    ServiceUnavailable,
+};
+const _wellKnownCtorMap = {
+    '400': BadRequest,
+    '401': Unauthorized,
+    '403': Forbidden,
+    '404': NotFound,
+    '405': MethodNotAllowed,
+    '408': RequestTimeout,
+    '409': Conflict,
+    '410': Gone,
+    '418': ImATeapot,
+    //
+    '500': InternalServerError,
+    '501': NotImplemented,
+    '502': BadGateway,
+    '503': ServiceUnavailable,
+};
+// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause
+const createHttpError = (code, message, body, cause) => {
+    const fallback = HTTP_STATUS.ERROR_SERVER.INTERNAL_SERVER_ERROR;
+    code = Number(code);
+    if (isNaN(code) || !(code >= 400 && code < 600))
+        code = fallback.CODE;
+    const found = HTTP_STATUS.findByCode(code);
+    const statusText = found?.TEXT ?? fallback.TEXT;
+    // opinionated convention
+    if (typeof body === 'string') {
+        // prettier-ignore
+        try {
+            body = JSON.parse(body);
+        }
+        catch (e) { }
+    }
+    // try to find the well known one, otherwise fallback to generic
+    const ctor = _wellKnownCtorMap[`${code}`] ?? HttpError;
+    let e = new ctor(message || statusText, { cause });
+    e.status = found?.CODE ?? fallback.CODE;
+    e.statusText = statusText;
+    e.body = body;
+    return e;
+};
+
+const _fetchRaw = async ({ method, path, data = null, token = null, headers = null, signal = null, credentials, }) => {
+    headers = Object.entries(headers || {}).map(([k, v]) => ({ [k.toLowerCase()]: v }));
+    const opts = { method, credentials, headers, signal };
+    if (data) {
+        const isObj = typeof data === 'object';
+        // multipart/form-data -- no explicit Content-Type
+        if (data instanceof FormData) {
+            opts.body = data;
+        }
+        // cover 99% use cases (may not fit all)
+        else {
+            // if not stated, assuming json
+            if (isObj || !headers['content-type']) {
+                opts.headers['content-type'] = 'application/json';
+            }
+            opts.body = JSON.stringify(data);
+        }
+    }
+    // opinionated convention
+    if (token) {
+        opts.headers['authorization'] = `Bearer ${token}`;
+    }
+    return await fetch(path, opts);
+};
+const _fetch = async (params, respHeaders = null, _dumpParams = false) => {
+    if (_dumpParams)
+        return params;
+    const r = await _fetchRaw(params);
+    if (params.raw)
+        return r;
+    // quick-n-dirty reference to headers (so it's still accessible over this api wrap)
+    if (respHeaders) {
+        Object.assign(respHeaders, [...r.headers.entries()].reduce((m, [k, v]) => ({ ...m, [k]: v }), {}), 
+        // adding status/text under special keys
+        {
+            __http_status_code__: r.status,
+            __http_status_text__: r.statusText,
+        });
+    }
+    let body = await r.text();
+    // prettier-ignore
+    try {
+        body = JSON.parse(body);
+    }
+    catch (e) { }
+    params.assert ??= true; // default is true
+    if (!r.ok && params.assert) {
+        throw createHttpError(r.status, null, body);
+    }
+    return body;
+};
+const createHttpApi = (base, defaults) => {
+    const _merge = (a, b) => {
+        const wrap = { result: a };
+        dset(wrap, 'result', b);
+        return wrap.result;
+    };
+    const _getDefs = async () => {
+        return new Promise(async (resolve) => {
+            if (typeof defaults === 'function') {
+                resolve(await defaults());
+            }
+            else {
+                resolve(defaults || {});
+            }
+        });
+    };
+    return {
+        // GET
+        async get(path, params, respHeaders = null, _dumpParams = false) {
+            path = `${base || ''}` + path;
+            return _fetch(_merge(await _getDefs(), { ...params, method: 'GET', path }), respHeaders, _dumpParams);
+        },
+        // POST
+        async post(path, data = null, params, respHeaders = null, _dumpParams = false) {
+            path = `${base || ''}` + path;
+            return _fetch(_merge(await _getDefs(), { ...(params || {}), data, method: 'POST', path }), respHeaders, _dumpParams);
+        },
+        // PUT
+        async put(path, data = null, params, respHeaders = null, _dumpParams = false) {
+            path = `${base || ''}` + path;
+            return _fetch(_merge(await _getDefs(), { ...(params || {}), data, method: 'PUT', path }), respHeaders, _dumpParams);
+        },
+        // PATCH
+        async patch(path, data = null, params, respHeaders = null, _dumpParams = false) {
+            path = `${base || ''}` + path;
+            return _fetch(_merge(await _getDefs(), { ...(params || {}), data, method: 'PATCH', path }), respHeaders, _dumpParams);
+        },
+        // DELETE
+        // https://stackoverflow.com/questions/299628/is-an-entity-body-allowed-for-an-http-delete-request
+        async del(path, data = null, params, respHeaders = null, _dumpParams = false) {
+            path = `${base || ''}` + path;
+            return _fetch(_merge(await _getDefs(), { ...(params || {}), data, method: 'DELETE', path }), respHeaders, _dumpParams);
+        },
+    };
+};
+
+export { HTTP_ERROR, HTTP_STATUS, createHttpApi, createHttpError };

package/dist/status.d.ts

@@ -0,0 +1,258 @@
+export declare class HTTP_STATUS {
+    static readonly INFO: {
+        CONTINUE: {
+            CODE: number;
+            TEXT: string;
+        };
+        SWITCHING_PROTOCOLS: {
+            CODE: number;
+            TEXT: string;
+        };
+        PROCESSING: {
+            CODE: number;
+            TEXT: string;
+        };
+        EARLY_HINTS: {
+            CODE: number;
+            TEXT: string;
+        };
+    };
+    static readonly SUCCESS: {
+        OK: {
+            CODE: number;
+            TEXT: string;
+        };
+        NON_AUTHORITATIVE_INFO: {
+            CODE: number;
+            TEXT: string;
+        };
+        ACCEPTED: {
+            CODE: number;
+            TEXT: string;
+        };
+        NO_CONTENT: {
+            CODE: number;
+            TEXT: string;
+        };
+        RESET_CONTENT: {
+            CODE: number;
+            TEXT: string;
+        };
+        PARTIAL_CONTENT: {
+            CODE: number;
+            TEXT: string;
+        };
+        MULTI_STATUS: {
+            CODE: number;
+            TEXT: string;
+        };
+        ALREADY_REPORTED: {
+            CODE: number;
+            TEXT: string;
+        };
+        IM_USED: {
+            CODE: number;
+            TEXT: string;
+        };
+    };
+    static readonly REDIRECT: {
+        MUTLIPLE_CHOICES: {
+            CODE: number;
+            TEXT: string;
+        };
+        MOVED_PERMANENTLY: {
+            CODE: number;
+            TEXT: string;
+        };
+        FOUND: {
+            CODE: number;
+            TEXT: string;
+        };
+        SEE_OTHER: {
+            CODE: number;
+            TEXT: string;
+        };
+        NOT_MODIFIED: {
+            CODE: number;
+            TEXT: string;
+        };
+        TEMPORARY_REDIRECT: {
+            CODE: number;
+            TEXT: string;
+        };
+        PERMANENT_REDIRECT: {
+            CODE: number;
+            TEXT: string;
+        };
+    };
+    static readonly ERROR_CLIENT: {
+        BAD_REQUEST: {
+            CODE: number;
+            TEXT: string;
+        };
+        UNAUTHORIZED: {
+            CODE: number;
+            TEXT: string;
+        };
+        PAYMENT_REQUIRED_EXPERIMENTAL: {
+            CODE: number;
+            TEXT: string;
+        };
+        FORBIDDEN: {
+            CODE: number;
+            TEXT: string;
+        };
+        NOT_FOUND: {
+            CODE: number;
+            TEXT: string;
+        };
+        METHOD_NOT_ALLOWED: {
+            CODE: number;
+            TEXT: string;
+        };
+        NOT_ACCEPTABLE: {
+            CODE: number;
+            TEXT: string;
+        };
+        PROXY_AUTHENTICATION_REQUIRED: {
+            CODE: number;
+            TEXT: string;
+        };
+        REQUEST_TIMEOUT: {
+            CODE: number;
+            TEXT: string;
+        };
+        CONFLICT: {
+            CODE: number;
+            TEXT: string;
+        };
+        GONE: {
+            CODE: number;
+            TEXT: string;
+        };
+        LENGTH_REQUIRED: {
+            CODE: number;
+            TEXT: string;
+        };
+        PRECONDITION_FAILED: {
+            CODE: number;
+            TEXT: string;
+        };
+        PAYLOAD_TOO_LARGE: {
+            CODE: number;
+            TEXT: string;
+        };
+        URI_TOO_LONG: {
+            CODE: number;
+            TEXT: string;
+        };
+        UNSUPPORTED_MEDIA_TYPE: {
+            CODE: number;
+            TEXT: string;
+        };
+        RANGE_NOT_SATISFIABLE: {
+            CODE: number;
+            TEXT: string;
+        };
+        EXPECTATION_FAILED: {
+            CODE: number;
+            TEXT: string;
+        };
+        IM_A_TEAPOT: {
+            CODE: number;
+            TEXT: string;
+        };
+        MISDIRECTED_REQUEST: {
+            CODE: number;
+            TEXT: string;
+        };
+        UNPROCESSABLE_CONTENT: {
+            CODE: number;
+            TEXT: string;
+        };
+        LOCKED: {
+            CODE: number;
+            TEXT: string;
+        };
+        FAILED_DEPENDENCY: {
+            CODE: number;
+            TEXT: string;
+        };
+        TOO_EARLY_EXPERIMENTAL: {
+            CODE: number;
+            TEXT: string;
+        };
+        UPGRADE_REQUIRED: {
+            CODE: number;
+            TEXT: string;
+        };
+        PRECONDITION_REQUIRED: {
+            CODE: number;
+            TEXT: string;
+        };
+        TOO_MANY_REQUESTS: {
+            CODE: number;
+            TEXT: string;
+        };
+        REQUEST_HEADER_FIELDS_TOO_LARGE: {
+            CODE: number;
+            TEXT: string;
+        };
+        UNAVAILABLE_FOR_LEGAL_REASONS: {
+            CODE: number;
+            TEXT: string;
+        };
+    };
+    static readonly ERROR_SERVER: {
+        INTERNAL_SERVER_ERROR: {
+            CODE: number;
+            TEXT: string;
+        };
+        NOT_IMPLEMENTED: {
+            CODE: number;
+            TEXT: string;
+        };
+        BAD_GATEWAY: {
+            CODE: number;
+            TEXT: string;
+        };
+        SERVICE_UNAVAILABLE: {
+            CODE: number;
+            TEXT: string;
+        };
+        GATEWAY_TIMEOUT: {
+            CODE: number;
+            TEXT: string;
+        };
+        HTTP_VERSION_NOT_SUPPORTED: {
+            CODE: number;
+            TEXT: string;
+        };
+        VARIANT_ALSO_NEGOTIATES: {
+            CODE: number;
+            TEXT: string;
+        };
+        INSUFFICIENT_STORAGE: {
+            CODE: number;
+            TEXT: string;
+        };
+        LOOP_DETECTED: {
+            CODE: number;
+            TEXT: string;
+        };
+        NOT_EXTENDED: {
+            CODE: number;
+            TEXT: string;
+        };
+        NETWORK_AUTH_REQUIRED: {
+            CODE: number;
+            TEXT: string;
+        };
+    };
+    static findByCode(code: number | string): {
+        CODE: number;
+        TEXT: string;
+        _TYPE: string;
+        _KEY: string;
+    } | null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/http-utils",
-	"version": "1.1.0",
+	"version": "1.2.0",
 	"description": "Misc DRY http fetch related helpers",
 	"type": "module",
 	"main": "./dist/index.cjs",
@@ -9,6 +9,9 @@
 		"require": "./dist/index.cjs",
 		"import": "./dist/index.js"
 	},
+	"files": [
+		"dist"
+	],
 	"scripts": {
 		"clean": "rimraf dist/*",
 		"prettier": "prettier --write \"{src,tests}/**/*.{js,ts,json}\"",

package/.editorconfig

@@ -1,12 +0,0 @@
-root = true
-
-[*]
-charset = utf-8
-end_of_line = lf
-insert_final_newline = true
-indent_style = tab
-trim_trailing_whitespace = true
-
-[package.json]
-indent_style = space
-indent_size = 2

package/.prettierignore

@@ -1 +0,0 @@
-/node_modules/

package/.prettierrc.yaml

@@ -1,5 +0,0 @@
-printWidth: 90
-singleQuote: true
-trailingComma: es5
-useTabs: true
-arrowParens: always

package/rollup.config.js

@@ -1,15 +0,0 @@
-import fs from "node:fs";
-import typescript from '@rollup/plugin-typescript';
-
-const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'))
-
-export default [
-	{
-		input: 'src/index.ts',
-		plugins: [ typescript() ],
-		output: [
-			{ file: pkg.main, format: 'cjs' },
-			{ file: pkg.module, format: 'es' }
-		]
-	}
-];