@vida-global/core 1.4.4 → 1.4.5

package/lib/http/README.md

@@ -30,3 +30,13 @@ const body = {baz: 1, ban: 2};
 const response = await client.post("/foo/bar", { body });
 ```
 
+## Aborting requests
+All request methods accept `timeout` (ms) and/or a caller-supplied `signal` (`AbortSignal`). When both are provided, they are composed via `AbortSignal.any` — whichever fires first aborts the request. If the request is aborted (by the timeout or the external signal), an `HttpAbortError` is thrown with `reason` set to either `'timed out'` or `'aborted'`.
+
+```
+await client.post("/foo/bar", { body, timeout: 5000 });
+
+const ctrl = new AbortController();
+await client.get("/foo/bar", { signal: ctrl.signal });
+```
+

package/lib/http/client.js

@@ -1,38 +1,67 @@
-const { logger }    = require('../logger');
-const { HttpError } = require('./error');
+const { logger }                    = require('../logger');
+const { HttpError, HttpAbortError } = require('./error');
 
 
 class HttpClient {
-    async get(endpoint, { requestParams, headers }={}) {
+    async get(endpoint, { requestParams, headers, timeout, signal }={}) {
         return await this.#makeRequest(endpoint, "GET", arguments[1]);
     }
 
 
-    async post(endpoint, { body, headers }={}) {
+    async post(endpoint, { body, headers, timeout, signal }={}) {
         return await this.#makeRequest(endpoint, "POST", arguments[1]);
     }
 
 
-    async put(endpoint, { body, headers }={}) {
+    async put(endpoint, { body, headers, timeout, signal }={}) {
         return await this.#makeRequest(endpoint, "PUT", arguments[1]);
     }
 
 
-    async delete(endpoint, { requestParams, headers }={}) {
+    async delete(endpoint, { requestParams, headers, timeout, signal }={}) {
         return await this.#makeRequest(endpoint, "DELETE", arguments[1]);
     }
 
 
-    async #makeRequest(endpoint, method, { requestParams, body, headers }={}) {
+    async #makeRequest(endpoint, method, { requestParams, body, headers, timeout, signal }={}) {
         this.#logRequest(method, endpoint);
 
         endpoint            = `${this.urlRoot}${endpoint}`;
         const url           = new URL(endpoint);
         const requestData   = structuredClone(requestParams || body || {});
-        const payload       = this.#prepareRequestPayload(url, requestData, headers, method);
+        const payload       = this.#prepareRequestPayload(url, requestData, headers, method, timeout, signal);
 
-        const res  = await fetch(url.toString(), payload);
+        try {
+            const res = await fetch(url.toString(), payload);
+            return await this.#handleRequestResponse(res, payload);
+        } catch (err) {
+            this.#handleRequestError(err, payload, timeout, signal);
+        }
+    }
+
+
+    #handleRequestError(err, payload, timeout, externalSignal) {
+        if (this.#isAbortError(err)) {
+            const msg = this.#classifyAbortReason(timeout, externalSignal)
+            throw new HttpAbortError(msg, payload);
+        }
+        throw err;
+    }
+
+
+    #isAbortError(err) {
+        return err instanceof DOMException && (err.name === 'AbortError' || err.name === 'TimeoutError');
+    }
 
+
+    #classifyAbortReason(timeout, externalSignal) {
+        if (externalSignal?.aborted) return 'aborted';
+        if (timeout)                 return 'timed out';
+        return 'aborted';
+    }
+
+
+    async #handleRequestResponse(res, payload) {
         if (res.status && res.status < 300) {
             const json = await res.json();
             return {data: json, status: res.status};
@@ -42,7 +71,7 @@ class HttpClient {
     }
 
 
-    #prepareRequestPayload(url, requestData, headers, method) {
+    #prepareRequestPayload(url, requestData, headers, method, timeout, signal) {
         const payload = {};
 
         headers       ||= {};
@@ -50,10 +79,23 @@ class HttpClient {
         payload.method  = method;
         this.#addRequestData(payload, requestData, method, url, payload.headers);
 
+        const composedSignal = this.#composeSignal(signal, timeout);
+        if (composedSignal) payload.signal = composedSignal;
+
         return payload;
     }
 
 
+    #composeSignal(externalSignal, timeoutMs) {
+        const signals = [];
+        if (externalSignal) signals.push(externalSignal);
+        if (timeoutMs)      signals.push(AbortSignal.timeout(timeoutMs));
+        if (signals.length === 0) return undefined;
+        if (signals.length === 1) return signals[0];
+        return AbortSignal.any(signals);
+    }
+
+
     #addRequestData(payload, requestData, method, url, headers) {
         if (method == "POST" || method == "PUT") {
             payload.body = JSON.stringify(requestData || {});
@@ -123,7 +165,8 @@ class HttpClient {
 }
 
 
-module.exports = { 
+module.exports = {
   HttpClient,
-  HttpError
+  HttpError,
+  HttpAbortError
 }

package/lib/http/error.js

@@ -29,6 +29,24 @@ class HttpError extends Error {
 }
 
 
+class HttpAbortError extends Error {
+    #requestPayload;
+    #reason;
+
+
+    constructor(reason, requestPayload) {
+        super(`HTTP request ${reason}`);
+        this.#reason         = reason;
+        this.#requestPayload = requestPayload;
+    }
+
+
+    get reason()         { return this.#reason; }
+    get requestPayload() { return structuredClone(this.#requestPayload); }
+}
+
+
 module.exports = {
-  HttpError
+  HttpError,
+  HttpAbortError
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vida-global/core",
-    "version": "1.4.4",
+    "version": "1.4.5",
     "description": "Core libraries for supporting Vida development",
     "author": "",
     "license": "ISC",

package/test/http/client.test.js

@@ -1,6 +1,6 @@
-const { HttpClient } = require('../../lib/http/client');
-const { logger }     = require('../../lib/logger');
-const   Helpers      = require('./helpers/client');
+const { HttpClient, HttpAbortError } = require('../../lib/http/client');
+const { logger }                     = require('../../lib/logger');
+const   Helpers                      = require('./helpers/client');
 
 
 afterEach(() => {
@@ -90,4 +90,73 @@ describe('HttpClient', () => {
             });
         }
     });
+
+
+    describe('abort/timeout support', () => {
+        const client = new HttpClient();
+
+
+        it('passes a signal when timeout is provided', async () => {
+            await client.post(Helpers.apiUrl, { timeout: 5000 });
+
+            const callOpts = fetch.mock.calls[0][1];
+            expect(callOpts.signal).toBeInstanceOf(AbortSignal);
+        });
+
+
+        it('passes a signal when an external signal is provided', async () => {
+            const externalSignal = new AbortController().signal;
+
+            await client.post(Helpers.apiUrl, { signal: externalSignal });
+
+            const callOpts = fetch.mock.calls[0][1];
+            expect(callOpts.signal).toBe(externalSignal);
+        });
+
+
+        it('composes external signal with timeout', async () => {
+            const externalSignal = new AbortController().signal;
+
+            await client.post(Helpers.apiUrl, { signal: externalSignal, timeout: 5000 });
+
+            const callOpts = fetch.mock.calls[0][1];
+            expect(callOpts.signal).toBeInstanceOf(AbortSignal);
+            expect(callOpts.signal).not.toBe(externalSignal);
+        });
+
+
+        it('omits signal when neither timeout nor signal is provided', async () => {
+            await client.post(Helpers.apiUrl);
+
+            const callOpts = fetch.mock.calls[0][1];
+            expect(callOpts.signal).toBeUndefined();
+        });
+
+
+        it('throws HttpAbortError with reason "timed out" when fetch rejects with AbortError under a timeout', async () => {
+            global.fetch = jest.fn().mockRejectedValue(new DOMException('aborted', 'AbortError'));
+
+            await expect(client.post(Helpers.apiUrl, { timeout: 1 }))
+                .rejects.toBeInstanceOf(HttpAbortError);
+            await expect(client.post(Helpers.apiUrl, { timeout: 1 }))
+                .rejects.toMatchObject({ reason: 'timed out' });
+        });
+
+
+        it('throws HttpAbortError with reason "aborted" when caller-supplied signal aborts the fetch', async () => {
+            global.fetch = jest.fn().mockRejectedValue(new DOMException('aborted', 'AbortError'));
+            const externalSignal = new AbortController().signal;
+
+            await expect(client.post(Helpers.apiUrl, { signal: externalSignal }))
+                .rejects.toMatchObject({ reason: 'aborted' });
+        });
+
+
+        it('rethrows non-abort fetch errors unchanged', async () => {
+            const networkErr = new Error('connect ECONNREFUSED');
+            global.fetch = jest.fn().mockRejectedValue(networkErr);
+
+            await expect(client.post(Helpers.apiUrl)).rejects.toBe(networkErr);
+        });
+    });
 });