@marianmeres/http-utils 1.0.1 → 1.0.2

package/README.md

@@ -1 +1,51 @@
-# http-utils
+# @marianmeres/http-utils
+
+A few [sweet](https://en.wikipedia.org/wiki/Syntactic_sugar) `fetch` helpers.
+
+## Example
+
+```javascript
+import { HTTP_ERROR, HTTP_STATUS, createHttpApi } from '@marianmeres/http-utils';
+
+// create api helper
+const api = createHttpApi(
+    // optional base url
+    'https://api.example.com',
+    // optional lazy evaluated default fetch params (can be overridden per call)
+    async () => ({
+        token: await getApiTokenFromDb() // example
+    })
+
+// EXAMPLE: assuming `/resource` returns json {"some":"data"}
+const r = await api.get('/resource');
+assert(r.some === 'data');
+
+// EXAMPLE: assuming `/foo` returns 404 header and json {"message":"hey"}
+// by default always throws
+try {
+    const r = await api.get('/foo');
+} catch (e) {
+    // see HTTP_ERROR for more
+    assert(e instanceof HTTP_ERROR.NotFound);
+    assert(e.toString() === 'HttpNotFoundError: Not Found');
+    assert(e.status === HTTP_STATUS.ERROR_CLIENT.NOT_FOUND.CODE);
+    assert(e.statusText === HTTP_STATUS.ERROR_CLIENT.NOT_FOUND.TEXT);
+    assert(e.body.message === 'hey');
+}
+
+// EXAMPLE: assuming `/foo` returns 404 header and json {"message":"hey"}
+// will not throw if we pass false flag
+const r = await api.get('/foo', { assert: false });
+assert(r.message === 'hey');
+
+// EXAMPLE: assuming POST to `/resource` returns OK and json {"message":"created"}
+// the provided token below will override the one from the `getApiTokenFromDb()` call above
+const r = await api.post('/resource', { some: 'data' }, { token: 'my-api-token' });
+assert(r.message === 'created');
+
+// EXAMPLE: raw Response
+const r = await api.get('/resource', { raw: true });
+assert(r instanceof Response);
+```
+
+See [`HTTP_STATUS`](./src/status.ts) and [`HTTP_ERROR`](./src/error.ts) for more.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/http-utils",
-	"version": "1.0.1",
+	"version": "1.0.2",
 	"description": "Misc DRY http fetch related helpers",
 	"type": "module",
 	"main": "./dist/index.cjs",

package/src/api.ts

@@ -2,7 +2,7 @@ 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
+// there is no magic added over plain fetch calls, just more opinionated and dry api
 
 interface BaseParams {
 	method: 'GET' | 'POST' | 'PATCH' | 'DELETE' | 'PUT';
@@ -16,6 +16,7 @@ interface FetchParams {
 	signal?: any;
 	credentials?: null | 'omit' | 'same-origin' | 'include';
 	raw?: null | boolean;
+	assert?: null | boolean;
 }
 
 type BaseFetchParams = BaseParams & FetchParams; // Exclude<Drinks, Soda> |
@@ -84,7 +85,9 @@ const _fetch = async (
 	// prettier-ignore
 	try { body = JSON.parse(body); } catch (e) {}
 
-	if (!r.ok) {
+	params.assert ??= true; // default is true
+
+	if (!r.ok && params.assert) {
 		throw createHttpError(r.status, null, body);
 	}
 
@@ -92,6 +95,7 @@ const _fetch = async (
 };
 
 export const createHttpApi = (
+	base: string | null,
 	defaults?: Partial<BaseFetchParams> | (() => Promise<Partial<BaseFetchParams>>)
 ) => {
 	const _merge = (a: any, b: any): any => {
@@ -118,6 +122,7 @@ export const createHttpApi = (
 			respHeaders = null,
 			_dumpParams = false
 		) {
+			path = `${base || ''}` + path;
 			return _fetch(
 				_merge(await _getDefs(), { ...params, method: 'GET', path }),
 				respHeaders,
@@ -133,6 +138,7 @@ export const createHttpApi = (
 			respHeaders = null,
 			_dumpParams = false
 		) {
+			path = `${base || ''}` + path;
 			return _fetch(
 				_merge(await _getDefs(), { ...(params || {}), data, method: 'POST', path }),
 				respHeaders,
@@ -148,6 +154,7 @@ export const createHttpApi = (
 			respHeaders = null,
 			_dumpParams = false
 		) {
+			path = `${base || ''}` + path;
 			return _fetch(
 				_merge(await _getDefs(), { ...(params || {}), data, method: 'PUT', path }),
 				respHeaders,
@@ -163,6 +170,7 @@ export const createHttpApi = (
 			respHeaders = null,
 			_dumpParams = false
 		) {
+			path = `${base || ''}` + path;
 			return _fetch(
 				_merge(await _getDefs(), { ...(params || {}), data, method: 'PATCH', path }),
 				respHeaders,
@@ -179,6 +187,7 @@ export const createHttpApi = (
 			respHeaders = null,
 			_dumpParams = false
 		) {
+			path = `${base || ''}` + path;
 			return _fetch(
 				_merge(await _getDefs(), { ...(params || {}), data, method: 'DELETE', path }),
 				respHeaders,

package/src/status.ts

@@ -2,7 +2,7 @@ export class HTTP_STATUS {
 	// 1xx
 	// prettier-ignore
 	static readonly INFO = {
-        CONTINUE:                        { CODE: 100, TEXT: 'Continue' },
+		CONTINUE:                        { CODE: 100, TEXT: 'Continue' },
 		SWITCHING_PROTOCOLS:             { CODE: 101, TEXT: 'Switching Protocols' },
 		PROCESSING:                      { CODE: 102, TEXT: 'Processing' },
 		EARLY_HINTS:                     { CODE: 103, TEXT: 'Early Hints' },
@@ -11,7 +11,7 @@ export class HTTP_STATUS {
 	// 2xx
 	// prettier-ignore
 	static readonly SUCCESS = {
-        OK:                              { CODE: 200, TEXT: 'OK' },
+		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' },

package/tests/api.test.js

@@ -20,7 +20,7 @@ const collectBody = async (request) =>
 	});
 
 const suite = new TestRunner(path.basename(fileURLToPath(import.meta.url)), {
-	before: async () => {
+	beforeEach: async () => {
 		server = createServer(async (req, res) => {
 			res.setHeader('Content-Type', 'application/json');
 			if (req.url === '/echo') {
@@ -37,7 +37,7 @@ const suite = new TestRunner(path.basename(fileURLToPath(import.meta.url)), {
 		});
 		return new Promise((resolve) => server.listen(port, hostname, resolve));
 	},
-	after: async () => new Promise((resolve) => server.close(resolve)),
+	afterEach: async () => new Promise((resolve) => server.close(resolve)),
 });
 
 suite.test('createHttpApi GET', async () => {
@@ -49,6 +49,15 @@ suite.test('createHttpApi GET', async () => {
 	assert(respHeaders.__http_status_code__ === 200);
 });
 
+suite.test('createHttpApi base option', async () => {
+	let api = createHttpApi(url);
+	let respHeaders = {};
+
+	let r = await api.get(`/echo`, {}, respHeaders);
+	assert(r.foo === 'bar');
+	assert(respHeaders.__http_status_code__ === 200);
+});
+
 suite.test('createHttpApi RAW', async () => {
 	let api = createHttpApi();
 	let headers = {};
@@ -73,6 +82,23 @@ suite.test('createHttpApi error', async () => {
 	assert(err.body.some.deep === 'message');
 });
 
+suite.test('createHttpApi error { raw: true }', async () => {
+	let api = createHttpApi();
+
+	let r = await api.get(`${url}/asdf`, { raw: true });
+	assert(r instanceof Response);
+	assert(!r.ok);
+});
+
+suite.test('createHttpApi error { assert: false } does not throw', async () => {
+	let api = createHttpApi();
+	let respHeaders = {};
+
+	let r = await api.get(`${url}/asdf`, { assert: false }, respHeaders);
+	assert(r.some.deep === 'message');
+	assert(respHeaders.__http_status_code__ === 404);
+});
+
 suite.test('createHttpApi POST', async () => {
 	let api = createHttpApi();
 	let respHeaders = {};
@@ -83,7 +109,7 @@ suite.test('createHttpApi POST', async () => {
 });
 
 suite.test('createHttpApi merge default params', async () => {
-	let api = createHttpApi({
+	let api = createHttpApi(null, {
 		headers: { authorization: 'Bearer foo' },
 		method: 'must be ignored',
 		path: 'must be ignored',