@marianmeres/http-utils 1.0.1

package/.editorconfig

@@ -0,0 +1,12 @@
+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

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

package/.prettierrc.yaml

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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Marian Meres
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1 @@
+# http-utils

package/package.json

@@ -0,0 +1,45 @@
+{
+	"name": "@marianmeres/http-utils",
+	"version": "1.0.1",
+	"description": "Misc DRY http fetch related helpers",
+	"type": "module",
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.js",
+	"exports": {
+		"require": "./dist/index.cjs",
+		"import": "./dist/index.js"
+	},
+	"scripts": {
+		"clean": "rimraf dist/*",
+		"prettier": "prettier --write \"{src,tests}/**/*.{js,ts,json}\"",
+		"release": "release",
+		"release:patch": "release -v patch",
+		"test": "test-runner",
+		"build": "npm run clean && rollup -c"
+	},
+	"types": "./dist/index.d.ts",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/marianmeres/http-utils.git"
+	},
+	"author": "Marian Meres <marian@meres.sk>",
+	"license": "MIT",
+	"bugs": {
+		"url": "https://github.com/marianmeres/http-utils/issues"
+	},
+	"homepage": "https://github.com/marianmeres/http-utils#readme",
+	"devDependencies": {
+		"@marianmeres/release": "^1.1.2",
+		"@marianmeres/test-runner": "^2.0.16",
+		"@rollup/plugin-typescript": "^11.1.6",
+		"@types/node": "^22.3.0",
+		"prettier": "^3.3.3",
+		"rimraf": "^6.0.1",
+		"rollup": "^4.20.0",
+		"tslib": "^2.6.3",
+		"typescript": "^5.5.4"
+	},
+	"dependencies": {
+		"dset": "^3.1.3"
+	}
+}

package/rollup.config.js

@@ -0,0 +1,15 @@
+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' }
+		]
+	}
+];

package/src/api.ts

@@ -0,0 +1,189 @@
+import { dset } from 'dset/merge';
+import { createHttpError } from './error.js';
+
+// this is all very opinionated and may not be useful for every use case...
+// there is no magic added over plain fetch calls
+
+interface BaseParams {
+	method: 'GET' | 'POST' | 'PATCH' | 'DELETE' | 'PUT';
+	path: string;
+}
+
+interface FetchParams {
+	data?: any;
+	token?: string | null;
+	headers?: any;
+	signal?: any;
+	credentials?: null | 'omit' | 'same-origin' | 'include';
+	raw?: null | boolean;
+}
+
+type BaseFetchParams = BaseParams & FetchParams; // Exclude<Drinks, Soda> |
+
+const _fetchRaw = async ({
+	method,
+	path,
+	data = null,
+	token = null,
+	headers = null,
+	signal = null,
+	credentials,
+}: BaseFetchParams) => {
+	headers = Object.entries(headers || {}).map(([k, v]) => ({ [k.toLowerCase()]: v }));
+	const opts: any = { 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: BaseFetchParams,
+	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: string = await r.text();
+	// prettier-ignore
+	try { body = JSON.parse(body); } catch (e) {}
+
+	if (!r.ok) {
+		throw createHttpError(r.status, null, body);
+	}
+
+	return body;
+};
+
+export const createHttpApi = (
+	defaults?: Partial<BaseFetchParams> | (() => Promise<Partial<BaseFetchParams>>)
+) => {
+	const _merge = (a: any, b: any): any => {
+		const wrap = { result: a };
+		dset(wrap, 'result', b);
+		return wrap.result;
+	};
+
+	const _getDefs = async () => {
+		return new Promise<Partial<BaseFetchParams>>(async (resolve) => {
+			if (typeof defaults === 'function') {
+				resolve(await defaults());
+			} else {
+				resolve(defaults || {});
+			}
+		});
+	};
+
+	return {
+		// GET
+		async get(
+			path: string,
+			params?: FetchParams,
+			respHeaders = null,
+			_dumpParams = false
+		) {
+			return _fetch(
+				_merge(await _getDefs(), { ...params, method: 'GET', path }),
+				respHeaders,
+				_dumpParams
+			);
+		},
+
+		// POST
+		async post(
+			path: string,
+			data = null,
+			params?: FetchParams,
+			respHeaders = null,
+			_dumpParams = false
+		) {
+			return _fetch(
+				_merge(await _getDefs(), { ...(params || {}), data, method: 'POST', path }),
+				respHeaders,
+				_dumpParams
+			);
+		},
+
+		// PUT
+		async put(
+			path: string,
+			data = null,
+			params?: FetchParams,
+			respHeaders = null,
+			_dumpParams = false
+		) {
+			return _fetch(
+				_merge(await _getDefs(), { ...(params || {}), data, method: 'PUT', path }),
+				respHeaders,
+				_dumpParams
+			);
+		},
+
+		// PATCH
+		async patch(
+			path: string,
+			data = null,
+			params?: FetchParams,
+			respHeaders = null,
+			_dumpParams = false
+		) {
+			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: string,
+			data = null,
+			params?: FetchParams,
+			respHeaders = null,
+			_dumpParams = false
+		) {
+			return _fetch(
+				_merge(await _getDefs(), { ...(params || {}), data, method: 'DELETE', path }),
+				respHeaders,
+				_dumpParams
+			);
+		},
+	};
+};

package/src/error.ts

@@ -0,0 +1,162 @@
+import { HTTP_STATUS } from './status.js';
+
+// opinionated base for all
+class HttpError extends Error {
+	public name = 'HttpError';
+	public status = HTTP_STATUS.ERROR_SERVER.INTERNAL_SERVER_ERROR.CODE;
+	public statusText = HTTP_STATUS.ERROR_SERVER.INTERNAL_SERVER_ERROR.TEXT;
+	public body: string | null = null;
+}
+
+// some more specific instances of the well known ones...
+
+// client
+
+class BadRequest extends HttpError {
+	public name = 'HttpBadRequestError';
+	public status = HTTP_STATUS.ERROR_CLIENT.BAD_REQUEST.CODE;
+	public statusText = HTTP_STATUS.ERROR_CLIENT.BAD_REQUEST.TEXT;
+}
+
+class Unauthorized extends HttpError {
+	public name = 'HttpUnauthorizedError';
+	public status = HTTP_STATUS.ERROR_CLIENT.UNAUTHORIZED.CODE;
+	public statusText = HTTP_STATUS.ERROR_CLIENT.UNAUTHORIZED.TEXT;
+}
+
+class Forbidden extends HttpError {
+	public name = 'HttpForbiddenError';
+	public status = HTTP_STATUS.ERROR_CLIENT.FORBIDDEN.CODE;
+	public statusText = HTTP_STATUS.ERROR_CLIENT.FORBIDDEN.TEXT;
+}
+
+class NotFound extends HttpError {
+	public name = 'HttpNotFoundError';
+	public status = HTTP_STATUS.ERROR_CLIENT.NOT_FOUND.CODE;
+	public statusText = HTTP_STATUS.ERROR_CLIENT.NOT_FOUND.TEXT;
+}
+
+class MethodNotAllowed extends HttpError {
+	public name = 'HttpMethodNotAllowedError';
+	public status = HTTP_STATUS.ERROR_CLIENT.METHOD_NOT_ALLOWED.CODE;
+	public statusText = HTTP_STATUS.ERROR_CLIENT.METHOD_NOT_ALLOWED.TEXT;
+}
+
+class RequestTimeout extends HttpError {
+	public name = 'HttpRequestTimeoutError';
+	public status = HTTP_STATUS.ERROR_CLIENT.REQUEST_TIMEOUT.CODE;
+	public statusText = HTTP_STATUS.ERROR_CLIENT.REQUEST_TIMEOUT.TEXT;
+}
+
+class Conflict extends HttpError {
+	public name = 'HttpConflictError';
+	public status = HTTP_STATUS.ERROR_CLIENT.CONFLICT.CODE;
+	public statusText = HTTP_STATUS.ERROR_CLIENT.CONFLICT.TEXT;
+}
+
+class Gone extends HttpError {
+	public name = 'HttpGoneError';
+	public status = HTTP_STATUS.ERROR_CLIENT.GONE.CODE;
+	public statusText = HTTP_STATUS.ERROR_CLIENT.GONE.TEXT;
+}
+
+class ImATeapot extends HttpError {
+	public name = 'HttpImATeapotError';
+	public status = HTTP_STATUS.ERROR_CLIENT.IM_A_TEAPOT.CODE;
+	public statusText = HTTP_STATUS.ERROR_CLIENT.IM_A_TEAPOT.TEXT;
+}
+
+// server
+
+class InternalServerError extends HttpError {
+	public name = 'HttpInternalServerError';
+}
+
+class NotImplemented extends HttpError {
+	public name = 'HttpServiceUnavailableError';
+	public status = HTTP_STATUS.ERROR_SERVER.NOT_IMPLEMENTED.CODE;
+	public statusText = HTTP_STATUS.ERROR_SERVER.NOT_IMPLEMENTED.TEXT;
+}
+
+class BadGateway extends HttpError {
+	public name = 'HttpBadGatewayError';
+	public status = HTTP_STATUS.ERROR_SERVER.BAD_GATEWAY.CODE;
+	public statusText = HTTP_STATUS.ERROR_SERVER.BAD_GATEWAY.TEXT;
+}
+
+class ServiceUnavailable extends HttpError {
+	public name = 'HttpServiceUnavailableError';
+	public status = HTTP_STATUS.ERROR_SERVER.SERVICE_UNAVAILABLE.CODE;
+	public statusText = HTTP_STATUS.ERROR_SERVER.SERVICE_UNAVAILABLE.TEXT;
+}
+
+//
+export 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
+export const createHttpError = (
+	code: number | string,
+	message?: string | null,
+	body?: any,
+	cause?: any
+) => {
+	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}` as keyof typeof _wellKnownCtorMap] ?? HttpError;
+
+	let e = new ctor(message || statusText, { cause });
+	e.status = found?.CODE ?? fallback.CODE;
+	e.statusText = statusText;
+	e.body = body;
+
+	return e;
+};

package/src/index.ts

@@ -0,0 +1,3 @@
+export { HTTP_STATUS } from './status.js';
+export { HTTP_ERROR, createHttpError } from './error.js';
+export { createHttpApi } from './api.js';

package/src/status.ts

@@ -0,0 +1,107 @@
+export class HTTP_STATUS {
+	// 1xx
+	// prettier-ignore
+	static readonly 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 readonly 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 readonly 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 readonly 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 readonly 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: number | string
+	): { CODE: number; TEXT: string; _TYPE: string; _KEY: string } | null {
+		const keys: (keyof typeof HTTP_STATUS)[] = [
+			'INFO',
+			'SUCCESS',
+			'REDIRECT',
+			'ERROR_CLIENT',
+			'ERROR_SERVER',
+		];
+		for (const _TYPE of keys) {
+			for (const [_KEY, data] of Object.entries(HTTP_STATUS[_TYPE]) as any) {
+				if (data.CODE == code) {
+					return { ...data, _TYPE, _KEY };
+				}
+			}
+		}
+		return null;
+	}
+}

package/tests/api.test.js

@@ -0,0 +1,110 @@
+import { TestRunner } from '@marianmeres/test-runner';
+import { strict as assert } from 'node:assert';
+import { createServer } from 'node:http';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { HTTP_ERROR, createHttpApi } from '../dist/index.cjs';
+
+let server;
+const hostname = '127.0.0.1';
+const port = 3456;
+const url = `http://${hostname}:${port}`;
+
+// https://nodejs.org/en/learn/modules/anatomy-of-an-http-transaction
+const collectBody = async (request) =>
+	new Promise((resolve) => {
+		let body = [];
+		request
+			.on('data', (chunk) => body.push(chunk))
+			.on('end', () => resolve(Buffer.concat(body).toString()));
+	});
+
+const suite = new TestRunner(path.basename(fileURLToPath(import.meta.url)), {
+	before: async () => {
+		server = createServer(async (req, res) => {
+			res.setHeader('Content-Type', 'application/json');
+			if (req.url === '/echo') {
+				res.statusCode = 200;
+				if (req.method === 'POST') {
+					res.end(await collectBody(req));
+				} else {
+					res.end('{"foo":"bar"}');
+				}
+			} else {
+				res.statusCode = 404;
+				res.end('{"some":{"deep":"message"}}');
+			}
+		});
+		return new Promise((resolve) => server.listen(port, hostname, resolve));
+	},
+	after: async () => new Promise((resolve) => server.close(resolve)),
+});
+
+suite.test('createHttpApi GET', async () => {
+	let api = createHttpApi();
+	let respHeaders = {};
+
+	let r = await api.get(`${url}/echo`, {}, respHeaders);
+	assert(r.foo === 'bar');
+	assert(respHeaders.__http_status_code__ === 200);
+});
+
+suite.test('createHttpApi RAW', async () => {
+	let api = createHttpApi();
+	let headers = {};
+
+	// raw
+	let r = await api.get(`${url}/echo`, { raw: true });
+	assert(r instanceof Response);
+});
+
+suite.test('createHttpApi error', async () => {
+	let api = createHttpApi();
+
+	let err;
+	try {
+		let r = await api.get(`${url}/asdf`);
+		assert(false); // must not be reached
+	} catch (e) {
+		err = e;
+	}
+
+	assert(err instanceof HTTP_ERROR.NotFound);
+	assert(err.body.some.deep === 'message');
+});
+
+suite.test('createHttpApi POST', async () => {
+	let api = createHttpApi();
+	let respHeaders = {};
+
+	let r = await api.post(`${url}/echo`, { hey: 'ho' }, {}, respHeaders);
+	assert(r.hey === 'ho');
+	assert(respHeaders.__http_status_code__ === 200);
+});
+
+suite.test('createHttpApi merge default params', async () => {
+	let api = createHttpApi({
+		headers: { authorization: 'Bearer foo' },
+		method: 'must be ignored',
+		path: 'must be ignored',
+		credentials: 'include',
+	});
+
+	const params = await api.post(
+		'/hoho',
+		{ foo: 'bar' },
+		{ headers: { hey: 'ho' } },
+		null,
+		true
+	);
+	// console.log(params);
+
+	assert(params.headers.authorization === 'Bearer foo');
+	assert(params.headers.hey === 'ho');
+	assert(params.method === 'POST');
+	assert(params.path === '/hoho');
+	assert(params.credentials === 'include');
+	assert(params.data.foo === 'bar');
+});
+
+export default suite;

package/tests/utils.test.js

@@ -0,0 +1,64 @@
+import { TestRunner } from '@marianmeres/test-runner';
+import { strict as assert } from 'node:assert';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { HTTP_ERROR, HTTP_STATUS, createHttpError } from '../dist/index.cjs';
+
+const suite = new TestRunner(path.basename(fileURLToPath(import.meta.url)));
+
+suite.test('HTTP_STATUS.findByCode', () => {
+	const s = HTTP_STATUS.findByCode(200);
+	assert(s.CODE === 200);
+	assert(s.TEXT === 'OK');
+	assert(s._TYPE === 'SUCCESS');
+	assert(s._KEY === 'OK');
+});
+
+suite.test('HTTP_ERROR', () => {
+	let e = new HTTP_ERROR.HttpError();
+	assert(e.toString() === 'HttpError');
+	assert(e.status === HTTP_STATUS.ERROR_SERVER.INTERNAL_SERVER_ERROR.CODE);
+
+	// random client pick
+	e = new HTTP_ERROR.Unauthorized('Foo');
+	assert(e.toString() === 'HttpUnauthorizedError: Foo');
+	assert(e.status === HTTP_STATUS.ERROR_CLIENT.UNAUTHORIZED.CODE);
+	assert(e.statusText === HTTP_STATUS.ERROR_CLIENT.UNAUTHORIZED.TEXT);
+
+	// random server pick
+	e = new HTTP_ERROR.BadGateway('Foo');
+	assert(e.toString() === 'HttpBadGatewayError: Foo');
+	assert(e.status === HTTP_STATUS.ERROR_SERVER.BAD_GATEWAY.CODE);
+	assert(e.statusText === HTTP_STATUS.ERROR_SERVER.BAD_GATEWAY.TEXT);
+});
+
+suite.test('createHttpErrorByCode', () => {
+	// well known
+	let e = createHttpError(404, null, '{"foo":"bar"}', { baz: 'bat' });
+
+	assert(e instanceof HTTP_ERROR.NotFound);
+	assert(e.toString() === 'HttpNotFoundError: Not Found');
+	assert(e.body.foo === 'bar');
+	assert(e.cause.baz === 'bat');
+
+	// NOT well known
+	e = createHttpError(423, null, '{invalid json}', 123);
+	assert(e instanceof HTTP_ERROR.HttpError);
+	assert(e.toString() === 'HttpError: Locked');
+	assert(e.body === '{invalid json}');
+	assert(e.cause === 123);
+
+	// unknown code must fall back to 500
+	e = createHttpError(123, null, '123');
+	assert(e instanceof HTTP_ERROR.InternalServerError);
+	assert(e.toString() === 'HttpInternalServerError: Internal Server Error');
+	assert(e.body === 123); // '123' is a valid json string
+	assert(e.cause === undefined);
+
+	// custom message
+	e = createHttpError(123, 'Hey', '123');
+	assert(e.toString() === 'HttpInternalServerError: Hey');
+	assert(e.body === 123);
+});
+
+export default suite;

package/tsconfig.json

@@ -0,0 +1,113 @@
+{
+	"include": ["src"],
+	"exclude": ["node_modules"],
+	"compilerOptions": {
+		/* Visit https://aka.ms/tsconfig to read more about this file */
+
+		/* Projects */
+		// "incremental": true,                              /* Save .tsbuildinfo files to allow for incremental compilation of projects. */
+		// "composite": true,                                /* Enable constraints that allow a TypeScript project to be used with project references. */
+		// "tsBuildInfoFile": "./.tsbuildinfo",              /* Specify the path to .tsbuildinfo incremental compilation file. */
+		// "disableSourceOfProjectReferenceRedirect": true,  /* Disable preferring source files instead of declaration files when referencing composite projects. */
+		// "disableSolutionSearching": true,                 /* Opt a project out of multi-project reference checking when editing. */
+		// "disableReferencedProjectLoad": true,             /* Reduce the number of projects loaded automatically by TypeScript. */
+
+		/* Language and Environment */
+		"target": "ESNext" /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */,
+		"lib": [
+			"ESNext"
+		] /* Specify a set of bundled library declaration files that describe the target runtime environment. */,
+		// "jsx": "preserve",                                /* Specify what JSX code is generated. */
+		// "experimentalDecorators": true,                   /* Enable experimental support for legacy experimental decorators. */
+		// "emitDecoratorMetadata": true,                    /* Emit design-type metadata for decorated declarations in source files. */
+		// "jsxFactory": "",                                 /* Specify the JSX factory function used when targeting React JSX emit, e.g. 'React.createElement' or 'h'. */
+		// "jsxFragmentFactory": "",                         /* Specify the JSX Fragment reference used for fragments when targeting React JSX emit e.g. 'React.Fragment' or 'Fragment'. */
+		// "jsxImportSource": "",                            /* Specify module specifier used to import the JSX factory functions when using 'jsx: react-jsx*'. */
+		// "reactNamespace": "",                             /* Specify the object invoked for 'createElement'. This only applies when targeting 'react' JSX emit. */
+		// "noLib": true,                                    /* Disable including any library files, including the default lib.d.ts. */
+		// "useDefineForClassFields": true,                  /* Emit ECMAScript-standard-compliant class fields. */
+		// "moduleDetection": "auto",                        /* Control what method is used to detect module-format JS files. */
+
+		/* Modules */
+		"module": "ESNext" /* Specify what module code is generated. */,
+		"rootDir": "src" /* Specify the root folder within your source files. */,
+		"moduleResolution": "Node" /* Specify how TypeScript looks up a file from a given module specifier. */,
+		// "baseUrl": "./",                                  /* Specify the base directory to resolve non-relative module names. */
+		// "paths": {},                                      /* Specify a set of entries that re-map imports to additional lookup locations. */
+		// "rootDirs": [],                                   /* Allow multiple folders to be treated as one when resolving modules. */
+		// "typeRoots": [],                                  /* Specify multiple folders that act like './node_modules/@types'. */
+		// "types": [],                                      /* Specify type package names to be included without being referenced in a source file. */
+		// "allowUmdGlobalAccess": true,                     /* Allow accessing UMD globals from modules. */
+		// "moduleSuffixes": [],                             /* List of file name suffixes to search when resolving a module. */
+		// "allowImportingTsExtensions": true,               /* Allow imports to include TypeScript file extensions. Requires '--moduleResolution bundler' and either '--noEmit' or '--emitDeclarationOnly' to be set. */
+		// "resolvePackageJsonExports": true,                /* Use the package.json 'exports' field when resolving package imports. */
+		// "resolvePackageJsonImports": true,                /* Use the package.json 'imports' field when resolving imports. */
+		// "customConditions": [],                           /* Conditions to set in addition to the resolver-specific defaults when resolving imports. */
+		// "resolveJsonModule": true,                        /* Enable importing .json files. */
+		// "allowArbitraryExtensions": true,                 /* Enable importing files with any extension, provided a declaration file is present. */
+		// "noResolve": true,                                /* Disallow 'import's, 'require's or '<reference>'s from expanding the number of files TypeScript should add to a project. */
+
+		/* JavaScript Support */
+		// "allowJs": true,                                  /* Allow JavaScript files to be a part of your program. Use the 'checkJS' option to get errors from these files. */
+		// "checkJs": true,                                  /* Enable error reporting in type-checked JavaScript files. */
+		// "maxNodeModuleJsDepth": 1,                        /* Specify the maximum folder depth used for checking JavaScript files from 'node_modules'. Only applicable with 'allowJs'. */
+
+		/* Emit */
+		"declaration": true /* Generate .d.ts files from TypeScript and JavaScript files in your project. */,
+		// "declarationMap": true,                           /* Create sourcemaps for d.ts files. */
+		// "emitDeclarationOnly": true,                      /* Only output d.ts files and not JavaScript files. */
+		// "sourceMap": true,                                /* Create source map files for emitted JavaScript files. */
+		// "inlineSourceMap": true,                          /* Include sourcemap files inside the emitted JavaScript. */
+		// "outFile": "./",                                  /* Specify a file that bundles all outputs into one JavaScript file. If 'declaration' is true, also designates a file that bundles all .d.ts output. */
+		"outDir": "dist" /* Specify an output folder for all emitted files. */,
+		// "removeComments": true,                           /* Disable emitting comments. */
+		// "noEmit": true,                                   /* Disable emitting files from a compilation. */
+		// "importHelpers": true,                            /* Allow importing helper functions from tslib once per project, instead of including them per-file. */
+		// "importsNotUsedAsValues": "remove",               /* Specify emit/checking behavior for imports that are only used for types. */
+		// "downlevelIteration": true,                       /* Emit more compliant, but verbose and less performant JavaScript for iteration. */
+		// "sourceRoot": "",                                 /* Specify the root path for debuggers to find the reference source code. */
+		// "mapRoot": "",                                    /* Specify the location where debugger should locate map files instead of generated locations. */
+		// "inlineSources": true,                            /* Include source code in the sourcemaps inside the emitted JavaScript. */
+		// "emitBOM": true,                                  /* Emit a UTF-8 Byte Order Mark (BOM) in the beginning of output files. */
+		// "newLine": "crlf",                                /* Set the newline character for emitting files. */
+		// "stripInternal": true,                            /* Disable emitting declarations that have '@internal' in their JSDoc comments. */
+		// "noEmitHelpers": true,                            /* Disable generating custom helper functions like '__extends' in compiled output. */
+		// "noEmitOnError": true,                            /* Disable emitting files if any type checking errors are reported. */
+		// "preserveConstEnums": true,                       /* Disable erasing 'const enum' declarations in generated code. */
+		// "declarationDir": "./",                           /* Specify the output directory for generated declaration files. */
+		// "preserveValueImports": true,                     /* Preserve unused imported values in the JavaScript output that would otherwise be removed. */
+
+		/* Interop Constraints */
+		// "isolatedModules": true,                          /* Ensure that each file can be safely transpiled without relying on other imports. */
+		// "verbatimModuleSyntax": true,                     /* Do not transform or elide any imports or exports not marked as type-only, ensuring they are written in the output file's format based on the 'module' setting. */
+		// "allowSyntheticDefaultImports": true,             /* Allow 'import x from y' when a module doesn't have a default export. */
+		"esModuleInterop": true /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */,
+		// "preserveSymlinks": true,                         /* Disable resolving symlinks to their realpath. This correlates to the same flag in node. */
+		"forceConsistentCasingInFileNames": true /* Ensure that casing is correct in imports. */,
+
+		/* Type Checking */
+		"strict": true /* Enable all strict type-checking options. */,
+		// "noImplicitAny": true,                            /* Enable error reporting for expressions and declarations with an implied 'any' type. */
+		// "strictNullChecks": true,                         /* When type checking, take into account 'null' and 'undefined'. */
+		// "strictFunctionTypes": true,                      /* When assigning functions, check to ensure parameters and the return values are subtype-compatible. */
+		// "strictBindCallApply": true,                      /* Check that the arguments for 'bind', 'call', and 'apply' methods match the original function. */
+		// "strictPropertyInitialization": true,             /* Check for class properties that are declared but not set in the constructor. */
+		// "noImplicitThis": true,                           /* Enable error reporting when 'this' is given the type 'any'. */
+		// "useUnknownInCatchVariables": true,               /* Default catch clause variables as 'unknown' instead of 'any'. */
+		// "alwaysStrict": true,                             /* Ensure 'use strict' is always emitted. */
+		// "noUnusedLocals": true,                           /* Enable error reporting when local variables aren't read. */
+		// "noUnusedParameters": true,                       /* Raise an error when a function parameter isn't read. */
+		// "exactOptionalPropertyTypes": true,               /* Interpret optional property types as written, rather than adding 'undefined'. */
+		// "noImplicitReturns": true,                        /* Enable error reporting for codepaths that do not explicitly return in a function. */
+		// "noFallthroughCasesInSwitch": true,               /* Enable error reporting for fallthrough cases in switch statements. */
+		// "noUncheckedIndexedAccess": true,                 /* Add 'undefined' to a type when accessed using an index. */
+		// "noImplicitOverride": true,                       /* Ensure overriding members in derived classes are marked with an override modifier. */
+		// "noPropertyAccessFromIndexSignature": true,       /* Enforces using indexed accessors for keys declared using an indexed type. */
+		// "allowUnusedLabels": true,                        /* Disable error reporting for unused labels. */
+		// "allowUnreachableCode": true,                     /* Disable error reporting for unreachable code. */
+
+		/* Completeness */
+		// "skipDefaultLibCheck": true /* Skip type checking .d.ts files that are included with TypeScript. */,
+		"skipLibCheck": true /* Skip type checking all .d.ts files. */
+	}
+}