@brandup/ui-ajax 1.0.44 → 2.0.2

package/README.md

@@ -12,7 +12,7 @@ npm i @brandup/ui-ajax@latest
 
 ## AJAX request
 
-Simplify async ajax request method.
+Simplify async ajax request method. `request` is the `fetch`-based, promise-returning API.
 
 ```
 import { request } from "@brandup/ui-ajax";
@@ -21,10 +21,13 @@ await request({
 		url?: string | null;
 		query?: QueryData | null;
 		method?: AJAXMethod | null;
+		mode?: RequestMode;
+		credentials?: RequestCredentials;
 		timeout?: number | null;
 		headers?: { [key: string]: string } | null;
-		type?: AJAXReqestType | null;
+		type?: AJAXRequestType | null;
 		data?: string | object | Blob | FormData | HTMLFormElement | null;
+		abort?: AbortSignal;
 		success?: ResponseDelegate | null;
 		error?: ErrorDelegate | null;
 		disableCache?: boolean | null;
@@ -42,15 +45,49 @@ await request({
 	.catch(reason => console.error(reason));
 ```
 
+The response body is parsed by `Content-Type`: JSON, `text/html`, `text/plain`, otherwise a `Blob`. The default `timeout` is `30000` ms and `credentials` defaults to `"include"`.
+
 ### Request cancellation
 
+A request is aborted when its `timeout` elapses, when the `abort` option signals, or when the second `abortSignal` argument signals.
+
 ```
 import { request } from "@brandup/ui-ajax";
 
 const cancellation = new AbortController();
 
-await request({ }, cancellation.signal)
+await request({ /* request options */ }, cancellation.signal)
 	.catch(reason => console.error(reason));
+
+cancellation.abort();
+```
+
+### Disable cache
+
+Set `disableCache: true` to bypass HTTP caching. In `request` (fetch) this sends `cache: "no-store"`; in `ajaxRequest` (XHR) it appends a `_=<timestamp>` cache-busting query parameter.
+
+```
+await request({ url: "/api/data", disableCache: true });
+```
+
+## AJAX request with XMLHttpRequest
+
+`ajaxRequest` is the `XMLHttpRequest`-based API. It always sends credentials, delivers results via the `success`/`error` callbacks (it does not return a promise), and returns the underlying `XMLHttpRequest` so the call can be aborted. Unlike `request`, there is no `blob` response type.
+
+```
+import { ajaxRequest } from "@brandup/ui-ajax";
+
+const xhr = ajaxRequest({
+	url: "/api/data",
+	method: "POST",
+	data: { name: "value" },
+	success: response => {
+		// response.status, response.data, response.type, ...
+	},
+	error: (request, reason) => console.error(reason)
+});
+
+xhr.abort(); // cancel the request
 ```
 
 ## Queue requests
@@ -61,16 +98,33 @@ Sequential execution of AJAX requests.
 import { AjaxQueue } from "@brandup/ui-ajax";
 
 const queue = new AjaxQueue({
-	canRequest?: (request: AjaxRequest) => void | boolean;
+	canRequest?: (request: AjaxRequest) => boolean | void;
 	successRequest?: (request: AjaxRequest, response: AjaxResponse) => void;
 	errorRequest?: (response: AjaxRequest, reason?: any) => void;
 });
 
-queue.push({ request options });
+queue.push({ /* request options */ }); // enqueue a request (fire and forget)
+
+queue.push({ /* request options */ }, abortSignal); // with per-request cancellation
 
-queue.reset(); // clear queue without abort current request
+queue.reset(); // clear queue without aborting current request
 
 queue.reset(true); // abort current request and clear queue
 
-queue.destroy();
+queue.destroy(); // clear queue, abort current request; further push() throws
+```
+
+Queue state can be inspected via `queue.length` (waiting requests), `queue.isEmpty` (nothing waiting) and `queue.isFree` (nothing waiting and nothing executing).
+
+### Awaiting a queued request
+
+`enqueue` queues a request like `push`, but returns a promise that resolves with the response (or rejects with the failure reason). The request's own `success`/`error` callbacks are still invoked.
+
+```
+import { AjaxQueue } from "@brandup/ui-ajax";
+
+const queue = new AjaxQueue();
+
+const response = await queue.enqueue({ url: "/api/data" });
+// response.status, response.data, ...
 ```

package/dist/cjs/ajax-request.js

@@ -0,0 +1,125 @@
+'use strict';
+
+var helpers = require('./helpers.js');
+var internals = require('./internals.js');
+
+/**
+ * Performs an AJAX request using `XMLHttpRequest`, always with credentials.
+ *
+ * The response body is parsed by `Content-Type` into JSON, `text/plain` or `text/html`;
+ * unlike the fetch-based {@link request}, there is no `blob` response type. `disableCache`
+ * appends a `_=<timestamp>` cache-busting query parameter (rather than `cache: "no-store"`).
+ * Results and errors are delivered through `options.success` / `options.error`; this
+ * function does not return a promise.
+ *
+ * @param options Request options. `GET` requests must not carry `data`. `timeout` of `0` disables the timeout.
+ * @returns The underlying `XMLHttpRequest`, which can be used to `abort()` the request.
+ */
+const ajaxRequest = (options) => {
+    let url = options.url || location.href;
+    let { query } = options;
+    if (options.disableCache) {
+        if (!query)
+            query = {};
+        query["_"] = Date.now().toString();
+    }
+    url = helpers.addQuery(url, query);
+    const method = options.method ? options.method.toUpperCase() : "GET";
+    if (options.data && (method === "GET" || method === "HEAD"))
+        throw new Error(`${method} method does not support a request body.`);
+    internals.default.detectRequestType(options);
+    const prepared = internals.default.prepareRequest(options, options.data);
+    const xhr = new XMLHttpRequest();
+    xhr.withCredentials = true;
+    if (options.timeout === 0 || options.timeout)
+        xhr.timeout = options.timeout;
+    xhr.onreadystatechange = (_e) => {
+        if (xhr.readyState !== XMLHttpRequest.DONE)
+            return;
+        if (options.success) {
+            let responseData = null;
+            let responseType = "none";
+            const contentType = xhr.getResponseHeader("Content-Type");
+            if (xhr.response && contentType) {
+                if (contentType.includes("json")) {
+                    responseType = "json";
+                    try {
+                        responseData = JSON.parse(xhr.responseText);
+                    }
+                    catch (e) {
+                        if (options.error)
+                            options.error(options, e);
+                        return;
+                    }
+                }
+                else if (contentType.includes("text/plain")) {
+                    responseType = "text";
+                    responseData = xhr.responseText;
+                }
+                else if (contentType.includes("text/html")) {
+                    responseType = "html";
+                    responseData = xhr.responseText;
+                }
+            }
+            const xhrRef = xhr;
+            const headers = {
+                get(name) {
+                    return xhrRef.getResponseHeader(name);
+                },
+                has(name) {
+                    return !!xhrRef.getResponseHeader(name);
+                },
+                forEach(callbackfn, thisArg) {
+                    xhrRef.getAllResponseHeaders()
+                        .trim()
+                        .split(/[\r\n]+/)
+                        .filter(Boolean)
+                        .forEach(line => {
+                        const idx = line.indexOf(": ");
+                        const key = idx >= 0 ? line.substring(0, idx).toLowerCase() : line.toLowerCase();
+                        const value = idx >= 0 ? line.substring(idx + 2) : "";
+                        callbackfn.call(thisArg, value, key, {});
+                    });
+                }
+            };
+            options.success({
+                status: xhr.status,
+                url: xhr.responseURL,
+                redirected: false,
+                type: responseType,
+                contentType,
+                headers,
+                data: responseData,
+                state: options.state
+            });
+        }
+    };
+    xhr.onabort = (_e) => {
+        if (options.error)
+            options.error(options, new Error("Request aborted"));
+    };
+    xhr.onerror = (_e) => {
+        if (options.error)
+            options.error(options, new Error("Request network error"));
+    };
+    xhr.ontimeout = (_e) => {
+        if (options.error)
+            options.error(options, new Error("Request timeout"));
+    };
+    xhr.open(method, url, true);
+    xhr.setRequestHeader("X-Requested-With", "XMLHttpRequest");
+    for (const key in prepared.headers) {
+        const value = prepared.headers[key];
+        if (!value)
+            continue;
+        xhr.setRequestHeader(key, value);
+    }
+    if (method === "GET")
+        xhr.send();
+    else
+        xhr.send(prepared.body);
+    return xhr;
+};
+
+exports.ajaxRequest = ajaxRequest;
+//# sourceMappingURL=ajax-request.js.map

package/dist/cjs/ajax-request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ajax-request.js","sources":["../../../source/ajax-request.ts"],"sourcesContent":[null],"names":["helpers.addQuery","internals"],"mappings":"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"}

package/dist/cjs/helpers.js

@@ -0,0 +1,69 @@
+'use strict';
+
+/**
+ * Builds a `URLSearchParams` from query data or a `FormData`.
+ *
+ * Array values produce repeated keys; `null` values are skipped.
+ *
+ * @param query Source parameters.
+ * @returns The populated `URLSearchParams` (empty when `query` is nullish).
+ */
+const createQuery = (query) => {
+    const urlParams = new URLSearchParams();
+    if (!query)
+        return urlParams;
+    if (query instanceof FormData) {
+        query.forEach((value, key) => {
+            if (!key)
+                return;
+            urlParams.append(key, value.toString());
+        });
+    }
+    else {
+        for (const key in query) {
+            const val = query[key];
+            if (val === null)
+                continue;
+            if (Array.isArray(val))
+                val.forEach(v => urlParams.append(key, v));
+            else
+                urlParams.append(key, val);
+        }
+    }
+    return urlParams;
+};
+/**
+ * Appends query parameters to a URL, choosing `?` or `&` as appropriate.
+ *
+ * @param url Base URL.
+ * @param query Parameters to append; nothing is added when empty.
+ * @returns The resulting URL.
+ */
+const addQuery = (url, query) => {
+    if (query) {
+        const urlParams = createQuery(query);
+        if (urlParams.size) {
+            if (url.indexOf("?") === -1)
+                url += "?";
+            else
+                url += "&";
+            url += urlParams.toString();
+        }
+    }
+    return url;
+};
+/**
+ * Encodes a `FormData` as an `application/x-www-form-urlencoded` string.
+ *
+ * @param data Form data to encode.
+ * @returns The URL-encoded form string.
+ */
+const encodeForm = (data) => {
+    const query = createQuery(data);
+    return query.toString();
+};
+
+exports.addQuery = addQuery;
+exports.createQuery = createQuery;
+exports.encodeForm = encodeForm;
+//# sourceMappingURL=helpers.js.map

package/dist/cjs/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sources":["../../../source/helpers.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAEA;;;;;;;AAOG;AACH,MAAM,WAAW,GAAG,CAAC,KAAmC,KAAI;AAC3D,IAAA,MAAM,SAAS,GAAG,IAAI,eAAe,EAAE;AAEvC,IAAA,IAAI,CAAC,KAAK;AACT,QAAA,OAAO,SAAS;AAEjB,IAAA,IAAI,KAAK,YAAY,QAAQ,EAAE;QAC9B,KAAK,CAAC,OAAO,CAAC,CAAC,KAAyB,EAAE,GAAW,KAAI;AACxD,YAAA,IAAI,CAAC,GAAG;gBACP;YACD,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC;AACxC,QAAA,CAAC,CAAC;IACH;SACK;AACJ,QAAA,KAAK,MAAM,GAAG,IAAI,KAAK,EAAE;AACxB,YAAA,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC;YACtB,IAAI,GAAG,KAAK,IAAI;gBACf;AAED,YAAA,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;AACrB,gBAAA,GAAG,CAAC,OAAO,CAAC,CAAC,IAAI,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;;AAE1C,gBAAA,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC;QAC5B;IACD;AAEA,IAAA,OAAO,SAAS;AACjB;AAEA;;;;;;AAMG;AACH,MAAM,QAAQ,GAAG,CAAC,GAAW,EAAE,KAAmC,KAAI;IACrE,IAAI,KAAK,EAAE;AACV,QAAA,MAAM,SAAS,GAAG,WAAW,CAAC,KAAK,CAAC;AAEpC,QAAA,IAAI,SAAS,CAAC,IAAI,EAAE;YACnB,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE;gBAC1B,GAAG,IAAI,GAAG;;gBAEV,GAAG,IAAI,GAAG;AAEX,YAAA,GAAG,IAAI,SAAS,CAAC,QAAQ,EAAE;QAC5B;IACD;AAEA,IAAA,OAAO,GAAG;AACX;AAEA;;;;;AAKG;AACH,MAAM,UAAU,GAAG,CAAC,IAAc,KAAI;AACrC,IAAA,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC;AAC/B,IAAA,OAAO,KAAK,CAAC,QAAQ,EAAE;AACxB;;;;;;"}