@brandup/ui-ajax 1.0.44 → 2.0.2

package/dist/mjs/request.js

@@ -0,0 +1,106 @@
+import { addQuery } from './helpers.js';
+import internals from './internals.js';
+
+/**
+ * Performs an AJAX request using the Fetch API.
+ *
+ * The response body is parsed according to its `Content-Type`: JSON, `text/html`,
+ * `text/plain`, otherwise a `Blob`. `disableCache` maps to `cache: "no-store"`.
+ * The request is aborted when its `timeout` elapses (defaults to 30000 ms), or when
+ * `options.abort` or the `abortSignal` argument signals.
+ *
+ * @param options Request options. `GET`/`HEAD` requests must not carry `data`.
+ * @param abortSignal Optional additional signal used to cancel the request.
+ * @returns The parsed response. `options.success` is also invoked before resolving.
+ * @throws On network/abort/timeout errors, or for unsupported (opaque) response types; `options.error` is invoked before re-throwing.
+ */
+async function request(options, abortSignal) {
+    let { mode, credentials = "include" } = options;
+    let url = options.url || location.href;
+    url = addQuery(url, options.query);
+    const method = options.method ? options.method.toUpperCase() : "GET";
+    let body = options.data;
+    if (body && (method === "GET" || method === "HEAD"))
+        throw new Error(`${method} method does not support a request body.`);
+    internals.detectRequestType(options);
+    const prepared = internals.prepareRequest(options, body);
+    const abortSignals = [AbortSignal.timeout(options.timeout ?? internals.DEFAULT_TIMEOUT)];
+    if (options.abort)
+        abortSignals.push(options.abort);
+    if (abortSignal)
+        abortSignals.push(abortSignal);
+    try {
+        const response = await fetch(url, {
+            method,
+            headers: new Headers(prepared.headers),
+            cache: options.disableCache ? "no-store" : "default",
+            mode,
+            credentials,
+            redirect: "follow",
+            signal: AbortSignal.any(abortSignals),
+            body: prepared.body
+        });
+        let result;
+        switch (response.type) {
+            case "basic":
+            case "default":
+            case "cors": {
+                let responseData = null;
+                let responseType = "none";
+                let contentType = response.headers.get("content-type");
+                if (!response.redirected && response.body) {
+                    if (contentType) {
+                        const ctSplitIndex = contentType.indexOf(";");
+                        if (ctSplitIndex > 0)
+                            contentType = contentType.substring(0, ctSplitIndex);
+                        if (contentType.includes("json")) {
+                            responseType = "json";
+                            responseData = await response.json();
+                        }
+                        else if (contentType.includes("text/html")) {
+                            responseType = "html";
+                            responseData = await response.text();
+                        }
+                        else if (contentType.includes("text/plain")) {
+                            responseType = "text";
+                            responseData = await response.text();
+                        }
+                        else {
+                            responseType = "blob";
+                            responseData = await response.blob();
+                        }
+                    }
+                }
+                result = {
+                    status: response.status,
+                    url: response.url,
+                    redirected: response.redirected,
+                    type: responseType,
+                    contentType,
+                    headers: response.headers,
+                    data: responseData,
+                    state: options.state
+                };
+                break;
+            }
+            case "opaqueredirect":
+            case "opaque":
+                throw new Error(`Not supported response type: ${response.type}`);
+            case "error":
+                throw new Error("Response error.");
+            default:
+                throw new Error(`Unknown response type: ${response.type}`);
+        }
+        if (options.success)
+            options.success(result);
+        return result;
+    }
+    catch (error) {
+        if (options.error)
+            options.error(options, error);
+        throw error;
+    }
+}
+
+export { request };
+//# sourceMappingURL=request.js.map

package/dist/mjs/request.js.map

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

package/dist/types.d.ts

@@ -1,75 +1,189 @@
+/** HTTP method for an AJAX request. Common verbs are suggested, but any custom string is allowed. */
 type AJAXMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | string;
-type AJAXReqestType = "NONE" | "JSON" | "XML" | "FORM" | "FORMDATA" | "TEXT" | "BLOB";
+/** Request body kind. Controls the `Content-Type`/`Accept` headers and how `data` is serialized. When omitted it is auto-detected from `data`. */
+type AJAXRequestType = "NONE" | "JSON" | "XML" | "FORM" | "FORMDATA" | "TEXT" | "BLOB";
+/** @deprecated Renamed to {@link AJAXRequestType}. */
+type AJAXReqestType = AJAXRequestType;
+/** Resolved kind of the response body, derived from the response `Content-Type`. `"blob"` only occurs for the fetch-based {@link request}; `ajaxRequest` (XHR) never returns blob. */
 type ResponseType = "none" | "json" | "blob" | "text" | "html";
+/** Callback invoked with the parsed response on success. */
 type ResponseDelegate = (response: AjaxResponse) => void;
+/** Callback invoked when a request fails or is aborted. `reason` is the thrown error or an abort/timeout message. */
 type ErrorDelegate = (request: AjaxRequest, reason?: any) => void;
+/** Query string parameters. Each value may be a single string or an array (repeated key). */
 type QueryData = {
     [key: string]: string | string[];
 };
+/** Options describing an AJAX request. */
 interface AjaxRequest<TState = any> {
+    /** Target URL. Defaults to the current `location.href` when omitted. */
     url?: string | null;
+    /** Query string parameters appended to the URL. */
     query?: QueryData | null;
+    /** HTTP method. Defaults to `"GET"`; normalized to upper-case. */
     method?: AJAXMethod | null;
+    /** Fetch request mode (e.g. `"cors"`). Only honored by the fetch-based {@link request}. */
     mode?: RequestMode;
+    /** Fetch credentials policy. Defaults to `"include"` in {@link request}; XHR always sends credentials. */
     credentials?: RequestCredentials;
+    /** Timeout in milliseconds. {@link request} defaults to 30000 ms when omitted; `0` disables the XHR timeout. */
     timeout?: number | null;
+    /** Additional request headers. Entries with empty values are skipped. */
     headers?: {
         [key: string]: string;
     } | null;
-    type?: AJAXReqestType | null;
+    /** Body serialization kind. Auto-detected from `data` when omitted. */
+    type?: AJAXRequestType | null;
+    /** Request body. Not allowed for `GET` (and `HEAD` in {@link request}). */
     data?: string | object | Blob | FormData | HTMLFormElement | null;
+    /** Signal used to abort the request. */
     abort?: AbortSignal;
+    /** Called with the response on success. */
     success?: ResponseDelegate | null;
+    /** Called on failure, abort or timeout. */
     error?: ErrorDelegate | null;
+    /** When `true`, bypasses caching. {@link request} sends `cache: "no-store"`; `ajaxRequest` appends a `_=<timestamp>` cache-busting query param. */
     disableCache?: boolean | null;
+    /** Arbitrary state passed through to the response unchanged. */
     state?: TState | null;
 }
+/** Parsed result of an AJAX request. */
 interface AjaxResponse<TData = any, TState = any> {
+    /** HTTP status code. */
     status: number;
+    /** Whether the request was redirected. Always `false` for `ajaxRequest` (XHR). */
     redirected: boolean;
+    /** Final response URL. */
     url: string | null;
+    /** Resolved body kind derived from the response `Content-Type`. */
     type: ResponseType;
+    /** Raw `Content-Type` header value. */
     contentType: string | null;
+    /** Accessor over the response headers. */
     headers: ResponseHeaders;
+    /** Parsed response body, or `null` when there is no body. */
     data: TData | null;
+    /** State value carried over from the originating request. */
     state?: TState | null;
 }
+/** Read-only accessor over response headers, mirroring a subset of the Fetch `Headers` API. */
 interface ResponseHeaders {
+    /** Returns the value of the given header, or `null` if absent. */
     get(name: string): string | null;
+    /** Returns whether the given header is present. */
     has(name: string): boolean;
+    /** Iterates over each header value/name pair. */
     forEach(callbackfn: (value: string, key: string, parent: ResponseHeaders) => void, thisArg?: any): void;
 }
 
-/** Request with fetch. */
+/**
+ * Performs an AJAX request using the Fetch API.
+ *
+ * The response body is parsed according to its `Content-Type`: JSON, `text/html`,
+ * `text/plain`, otherwise a `Blob`. `disableCache` maps to `cache: "no-store"`.
+ * The request is aborted when its `timeout` elapses (defaults to 30000 ms), or when
+ * `options.abort` or the `abortSignal` argument signals.
+ *
+ * @param options Request options. `GET`/`HEAD` requests must not carry `data`.
+ * @param abortSignal Optional additional signal used to cancel the request.
+ * @returns The parsed response. `options.success` is also invoked before resolving.
+ * @throws On network/abort/timeout errors, or for unsupported (opaque) response types; `options.error` is invoked before re-throwing.
+ */
 declare function request<TData = any, TState = any>(options: AjaxRequest<TState>, abortSignal?: AbortSignal): Promise<AjaxResponse<TData, TState>>;
 
-/** Request with XMLHttpRequest. */
+/**
+ * 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.
+ */
 declare const ajaxRequest: (options: AjaxRequest) => XMLHttpRequest;
 
+/** Queue that executes AJAX requests one at a time, in the order they were added. */
 declare class AjaxQueue {
     private _options;
     private _requests;
-    private _curent;
+    private _current;
     private _destroyed;
+    /** @param options Optional queue-wide hooks. */
     constructor(options?: AjaxQueueOptions);
+    /** Number of requests waiting in the queue (excluding the one currently executing). */
     get length(): number;
+    /** `true` when nothing is queued and no request is currently executing. */
     get isFree(): boolean;
+    /** `true` when no requests are waiting in the queue (a request may still be executing). */
     get isEmpty(): boolean;
+    /**
+     * Adds a request to the queue. Starts executing immediately if the queue is idle.
+     *
+     * @param request Request options; its `success`/`error` callbacks are invoked as usual.
+     * @param abortSignal Optional signal used to cancel this specific request.
+     * @throws If the queue has been destroyed.
+     */
     push(request: AjaxRequest, abortSignal?: AbortSignal): void;
+    /**
+     * Adds a request to the queue and returns a promise for its response.
+     *
+     * Wraps {@link push}; the request's own `success`/`error` callbacks are still invoked,
+     * then the promise resolves with the response or rejects with the failure reason.
+     *
+     * @param request Request options.
+     * @param abortSignal Optional signal used to cancel this specific request.
+     * @returns A promise resolving with the {@link AjaxResponse}.
+     */
+    enqueue<TResponse = any>(request: AjaxRequest, abortSignal?: AbortSignal): Promise<AjaxResponse<TResponse, any>>;
+    /** @deprecated Renamed to {@link enqueue}. */
     enque<TResponse = any>(request: AjaxRequest, abortSignal?: AbortSignal): Promise<AjaxResponse<TResponse, any>>;
+    /**
+     * Clears all queued (not-yet-started) requests.
+     *
+     * @param cancelCurrentRequest When `true`, also aborts the request currently executing.
+     */
     reset(cancelCurrentRequest?: boolean): void;
+    /** Destroys the queue: clears pending requests and aborts the current one. Subsequent {@link push} calls throw. */
     destroy(): void;
     private __execute;
     private __next;
 }
+/** Queue-wide hooks invoked for every request processed by an {@link AjaxQueue}. */
 interface AjaxQueueOptions {
-    canRequest?: (request: AjaxRequest) => void | boolean;
+    /** Called before a request is sent; returning `false` skips it (it is dropped without being sent). */
+    canRequest?: (request: AjaxRequest) => boolean | void;
+    /** Called after a request completes successfully. */
     successRequest?: (request: AjaxRequest, response: AjaxResponse) => void;
+    /** Called when a request fails or is aborted. */
     errorRequest?: (response: AjaxRequest, reason?: any) => void;
 }
 
+/**
+ * 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).
+ */
 declare const createQuery: (query?: QueryData | FormData | null) => URLSearchParams;
+/**
+ * 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.
+ */
 declare const addQuery: (url: string, query?: QueryData | FormData | null) => string;
+/**
+ * Encodes a `FormData` as an `application/x-www-form-urlencoded` string.
+ *
+ * @param data Form data to encode.
+ * @returns The URL-encoded form string.
+ */
 declare const encodeForm: (data: FormData) => string;
 
 declare const helpers_addQuery: typeof addQuery;
@@ -84,4 +198,4 @@ declare namespace helpers {
 }
 
 export { AjaxQueue, helpers as RequestHelper, ajaxRequest, request };
-export type { AJAXMethod, AJAXReqestType, AjaxQueueOptions, AjaxRequest, AjaxResponse, ErrorDelegate, QueryData, ResponseDelegate, ResponseHeaders, ResponseType };
+export type { AJAXMethod, AJAXReqestType, AJAXRequestType, AjaxQueueOptions, AjaxRequest, AjaxResponse, ErrorDelegate, QueryData, ResponseDelegate, ResponseHeaders, ResponseType };

package/package.json

@@ -21,10 +21,18 @@
     "email": "it@brandup.online"
   },
   "license": "Apache-2.0",
-  "version": "1.0.44",
+  "version": "2.0.2",
   "main": "dist/cjs/index.js",
   "module": "dist/mjs/index.js",
   "types": "dist/types.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/mjs/index.js",
+      "require": "./dist/cjs/index.js"
+    }
+  },
   "files": [
     "dist",
     "README.md"