@c9up/aurora 0.1.7 → 0.1.8

package/dist/http.d.ts

@@ -28,6 +28,12 @@ export interface HttpClientOptions {
     token?: string | null | (() => string | null | undefined);
     /** Default `credentials` mode (e.g. `"include"` to send cookies). */
     credentials?: RequestCredentials;
+    /**
+     * Default timeout in ms — the request is aborted (rejecting with a
+     * `TimeoutError`) if it doesn't settle in time. Combined with a per-request
+     * `signal`, whichever fires first wins.
+     */
+    timeout?: number;
 }
 export interface HttpRequestOptions<T = unknown> {
     /** Query params appended to the URL. `null`/`undefined` values are skipped. */
@@ -36,8 +42,10 @@ export interface HttpRequestOptions<T = unknown> {
     headers?: Record<string, string>;
     /** Per-request bearer token override (`null` to force-omit). */
     token?: string | null;
-    /** Abort signal. */
+    /** Abort signal — abort it to cancel the request (e.g. on unmount / new keystroke). */
     signal?: AbortSignal;
+    /** Per-request timeout in ms (overrides the client default). Aborts with a `TimeoutError`. */
+    timeout?: number;
     /** `credentials` mode for this request. */
     credentials?: RequestCredentials;
     /**
@@ -54,6 +62,28 @@ export declare class HttpError extends Error {
     readonly data: unknown;
     constructor(response: Response, data: unknown);
 }
+/** Type guard for {@link HttpError} — clean `catch` narrowing without a cast. */
+export declare function isHttpError(value: unknown): value is HttpError;
+/**
+ * Whether `value` is an aborted/timed-out request error — an `AbortError`
+ * (cancelled via a `signal`) or a `TimeoutError` (the `timeout` option fired).
+ * Use it to silently ignore cancellations (e.g. a superseded search request).
+ */
+export declare function isAbortError(value: unknown): boolean;
+/**
+ * Outcome of a non-throwing request via {@link HttpClient.attempt}: a
+ * discriminated union a form submit can branch on (`if (r.ok)`) instead of
+ * wrapping every call in try/catch.
+ */
+export type HttpResult<T> = {
+    ok: true;
+    data: T;
+    error: null;
+} | {
+    ok: false;
+    data: null;
+    error: HttpError;
+};
 export declare class HttpClient {
     #private;
     constructor(options?: HttpClientOptions);
@@ -72,6 +102,20 @@ export declare class HttpClient {
     patch<T>(url: string, body?: unknown, options?: HttpRequestOptions<T>): Promise<T>;
     /** Send a request and return the raw `Response` (no parsing, no throw on non-2xx). */
     raw(method: string, url: string, body?: unknown, options?: HttpRequestOptions): Promise<Response>;
+    /**
+     * Run a request without throwing on a non-2xx response: returns a
+     * discriminated {@link HttpResult} so a form submit can branch
+     * (`if (r.ok) … else r.error.data`) instead of wrapping each call in
+     * try/catch. Genuine transport failures (offline, DNS) still reject —
+     * they're exceptional, not an HTTP error.
+     *
+     * ```js
+     * const r = await api.attempt(api.post('/auth/login', creds))
+     * if (r.ok) user(r.data)
+     * else fieldErrors(r.error.data)   // HttpError.data = parsed 4xx body
+     * ```
+     */
+    attempt<T>(request: Promise<T>): Promise<HttpResult<T>>;
     /** Derive a new client with merged defaults (e.g. a scope that adds a token). */
     extend(options: HttpClientOptions): HttpClient;
 }

package/dist/http.js

@@ -28,6 +28,23 @@ export class HttpError extends Error {
         this.data = data;
     }
 }
+/** Type guard for {@link HttpError} — clean `catch` narrowing without a cast. */
+export function isHttpError(value) {
+    return value instanceof HttpError;
+}
+/**
+ * Whether `value` is an aborted/timed-out request error — an `AbortError`
+ * (cancelled via a `signal`) or a `TimeoutError` (the `timeout` option fired).
+ * Use it to silently ignore cancellations (e.g. a superseded search request).
+ */
+export function isAbortError(value) {
+    const name = value instanceof Error
+        ? value.name
+        : typeof DOMException !== "undefined" && value instanceof DOMException
+            ? value.name
+            : undefined;
+    return name === "AbortError" || name === "TimeoutError";
+}
 /** Whether `body` should be JSON-encoded (vs. passed to `fetch` untouched). */
 function shouldJsonEncode(body) {
     if (body === null || typeof body !== "object") {
@@ -54,6 +71,26 @@ function hasHeader(headers, name) {
     }
     return false;
 }
+/** Merge abort signals into one (whichever fires first wins). `undefined` if none. */
+function combineSignals(signals) {
+    const present = signals.filter((s) => s !== undefined);
+    if (present.length <= 1)
+        return present[0];
+    if (typeof AbortSignal.any === "function")
+        return AbortSignal.any(present);
+    // Fallback for runtimes without AbortSignal.any.
+    const controller = new AbortController();
+    for (const signal of present) {
+        if (signal.aborted) {
+            controller.abort(signal.reason);
+            break;
+        }
+        signal.addEventListener("abort", () => controller.abort(signal.reason), {
+            once: true,
+        });
+    }
+    return controller.signal;
+}
 /** Parse a response by content-type; `null` for empty / no-content bodies. */
 async function parseBody(response) {
     if (response.status === 204 || response.status === 205)
@@ -71,11 +108,13 @@ export class HttpClient {
     #headers;
     #token;
     #credentials;
+    #timeout;
     constructor(options = {}) {
         this.#baseURL = options.baseURL ?? "";
         this.#headers = { ...options.headers };
         this.#token = options.token;
         this.#credentials = options.credentials;
+        this.#timeout = options.timeout;
     }
     /** Set a default header for every subsequent request (case-insensitive replace). Chainable. */
     setHeader(name, value) {
@@ -125,6 +164,30 @@ export class HttpClient {
     raw(method, url, body, options = {}) {
         return this.#send(method, url, body, options);
     }
+    /**
+     * Run a request without throwing on a non-2xx response: returns a
+     * discriminated {@link HttpResult} so a form submit can branch
+     * (`if (r.ok) … else r.error.data`) instead of wrapping each call in
+     * try/catch. Genuine transport failures (offline, DNS) still reject —
+     * they're exceptional, not an HTTP error.
+     *
+     * ```js
+     * const r = await api.attempt(api.post('/auth/login', creds))
+     * if (r.ok) user(r.data)
+     * else fieldErrors(r.error.data)   // HttpError.data = parsed 4xx body
+     * ```
+     */
+    async attempt(request) {
+        try {
+            return { ok: true, data: await request, error: null };
+        }
+        catch (error) {
+            if (error instanceof HttpError) {
+                return { ok: false, data: null, error };
+            }
+            throw error;
+        }
+    }
     /** Derive a new client with merged defaults (e.g. a scope that adds a token). */
     extend(options) {
         return new HttpClient({
@@ -132,6 +195,7 @@ export class HttpClient {
             headers: { ...this.#headers, ...options.headers },
             token: options.token ?? this.#token,
             credentials: options.credentials ?? this.#credentials,
+            timeout: options.timeout ?? this.#timeout,
         });
     }
     #resolveToken(override) {
@@ -177,11 +241,16 @@ export class HttpClient {
                 payload = body;
             }
         }
+        const timeout = options.timeout ?? this.#timeout;
+        const signal = combineSignals([
+            options.signal,
+            timeout !== undefined ? AbortSignal.timeout(timeout) : undefined,
+        ]);
         return fetch(this.#buildUrl(url, options.query), {
             method,
             headers,
             body: payload,
-            signal: options.signal,
+            signal,
             credentials: options.credentials ?? this.#credentials,
         });
     }

package/dist/index.d.ts

@@ -2,8 +2,8 @@ export type { CookieOptions, PersistedSignalOptions, ShareData, StorageArea, Web
 export { back, clipboard, cookie, forward, hash, mediaQuery, navigate, online, persistedSignal, prefersDark, queryParam, redirect, reload, replace, session, share, storage, visibility, WebStorage, windowSize, } from "./browser.js";
 export { component, onMount, onUnmount } from "./component.js";
 export { html, isTemplateResult } from "./html.js";
-export type { HttpClientOptions, HttpRequestOptions } from "./http.js";
-export { HttpClient, HttpError, http } from "./http.js";
+export type { HttpClientOptions, HttpRequestOptions, HttpResult, } from "./http.js";
+export { HttpClient, HttpError, http, isAbortError, isHttpError, } from "./http.js";
 export { hydrate } from "./hydrate.js";
 export { batch, effect, isSignal, memo, onCleanup, type ReadSignal, type Signal, signal, untrack, } from "./reactive.js";
 export { type Disposer, render } from "./render.js";

package/dist/index.js

@@ -1,7 +1,7 @@
 export { back, clipboard, cookie, forward, hash, mediaQuery, navigate, online, persistedSignal, prefersDark, queryParam, redirect, reload, replace, session, share, storage, visibility, WebStorage, windowSize, } from "./browser.js";
 export { component, onMount, onUnmount } from "./component.js";
 export { html, isTemplateResult } from "./html.js";
-export { HttpClient, HttpError, http } from "./http.js";
+export { HttpClient, HttpError, http, isAbortError, isHttpError, } from "./http.js";
 export { hydrate } from "./hydrate.js";
 export { batch, effect, isSignal, memo, onCleanup, signal, untrack, } from "./reactive.js";
 export { render } from "./render.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/aurora",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Aurora — reactive UI runtime for the Ream framework. Tagged-template DOM, signal-based state, isomorphic SSR + hydration, zero build step.",
   "license": "MIT",
   "type": "module",

package/src/http.ts

@@ -29,6 +29,12 @@ export interface HttpClientOptions {
 	token?: string | null | (() => string | null | undefined);
 	/** Default `credentials` mode (e.g. `"include"` to send cookies). */
 	credentials?: RequestCredentials;
+	/**
+	 * Default timeout in ms — the request is aborted (rejecting with a
+	 * `TimeoutError`) if it doesn't settle in time. Combined with a per-request
+	 * `signal`, whichever fires first wins.
+	 */
+	timeout?: number;
 }
 
 export interface HttpRequestOptions<T = unknown> {
@@ -38,8 +44,10 @@ export interface HttpRequestOptions<T = unknown> {
 	headers?: Record<string, string>;
 	/** Per-request bearer token override (`null` to force-omit). */
 	token?: string | null;
-	/** Abort signal. */
+	/** Abort signal — abort it to cancel the request (e.g. on unmount / new keystroke). */
 	signal?: AbortSignal;
+	/** Per-request timeout in ms (overrides the client default). Aborts with a `TimeoutError`. */
+	timeout?: number;
 	/** `credentials` mode for this request. */
 	credentials?: RequestCredentials;
 	/**
@@ -65,6 +73,35 @@ export class HttpError extends Error {
 	}
 }
 
+/** Type guard for {@link HttpError} — clean `catch` narrowing without a cast. */
+export function isHttpError(value: unknown): value is HttpError {
+	return value instanceof HttpError;
+}
+
+/**
+ * Whether `value` is an aborted/timed-out request error — an `AbortError`
+ * (cancelled via a `signal`) or a `TimeoutError` (the `timeout` option fired).
+ * Use it to silently ignore cancellations (e.g. a superseded search request).
+ */
+export function isAbortError(value: unknown): boolean {
+	const name =
+		value instanceof Error
+			? value.name
+			: typeof DOMException !== "undefined" && value instanceof DOMException
+				? value.name
+				: undefined;
+	return name === "AbortError" || name === "TimeoutError";
+}
+
+/**
+ * Outcome of a non-throwing request via {@link HttpClient.attempt}: a
+ * discriminated union a form submit can branch on (`if (r.ok)`) instead of
+ * wrapping every call in try/catch.
+ */
+export type HttpResult<T> =
+	| { ok: true; data: T; error: null }
+	| { ok: false; data: null; error: HttpError };
+
 /** Whether `body` should be JSON-encoded (vs. passed to `fetch` untouched). */
 function shouldJsonEncode(body: unknown): boolean {
 	if (body === null || typeof body !== "object") {
@@ -94,6 +131,27 @@ function hasHeader(headers: Record<string, string>, name: string): boolean {
 	return false;
 }
 
+/** Merge abort signals into one (whichever fires first wins). `undefined` if none. */
+function combineSignals(
+	signals: ReadonlyArray<AbortSignal | undefined>,
+): AbortSignal | undefined {
+	const present = signals.filter((s): s is AbortSignal => s !== undefined);
+	if (present.length <= 1) return present[0];
+	if (typeof AbortSignal.any === "function") return AbortSignal.any(present);
+	// Fallback for runtimes without AbortSignal.any.
+	const controller = new AbortController();
+	for (const signal of present) {
+		if (signal.aborted) {
+			controller.abort(signal.reason);
+			break;
+		}
+		signal.addEventListener("abort", () => controller.abort(signal.reason), {
+			once: true,
+		});
+	}
+	return controller.signal;
+}
+
 /** Parse a response by content-type; `null` for empty / no-content bodies. */
 async function parseBody(response: Response): Promise<unknown> {
 	if (response.status === 204 || response.status === 205) return null;
@@ -109,12 +167,14 @@ export class HttpClient {
 	readonly #headers: Record<string, string>;
 	readonly #token?: string | null | (() => string | null | undefined);
 	readonly #credentials?: RequestCredentials;
+	readonly #timeout?: number;
 
 	constructor(options: HttpClientOptions = {}) {
 		this.#baseURL = options.baseURL ?? "";
 		this.#headers = { ...options.headers };
 		this.#token = options.token;
 		this.#credentials = options.credentials;
+		this.#timeout = options.timeout;
 	}
 
 	/** Set a default header for every subsequent request (case-insensitive replace). Chainable. */
@@ -192,6 +252,30 @@ export class HttpClient {
 		return this.#send(method, url, body, options);
 	}
 
+	/**
+	 * Run a request without throwing on a non-2xx response: returns a
+	 * discriminated {@link HttpResult} so a form submit can branch
+	 * (`if (r.ok) … else r.error.data`) instead of wrapping each call in
+	 * try/catch. Genuine transport failures (offline, DNS) still reject —
+	 * they're exceptional, not an HTTP error.
+	 *
+	 * ```js
+	 * const r = await api.attempt(api.post('/auth/login', creds))
+	 * if (r.ok) user(r.data)
+	 * else fieldErrors(r.error.data)   // HttpError.data = parsed 4xx body
+	 * ```
+	 */
+	async attempt<T>(request: Promise<T>): Promise<HttpResult<T>> {
+		try {
+			return { ok: true, data: await request, error: null };
+		} catch (error) {
+			if (error instanceof HttpError) {
+				return { ok: false, data: null, error };
+			}
+			throw error;
+		}
+	}
+
 	/** Derive a new client with merged defaults (e.g. a scope that adds a token). */
 	extend(options: HttpClientOptions): HttpClient {
 		return new HttpClient({
@@ -199,6 +283,7 @@ export class HttpClient {
 			headers: { ...this.#headers, ...options.headers },
 			token: options.token ?? this.#token,
 			credentials: options.credentials ?? this.#credentials,
+			timeout: options.timeout ?? this.#timeout,
 		});
 	}
 
@@ -250,11 +335,17 @@ export class HttpClient {
 			}
 		}
 
+		const timeout = options.timeout ?? this.#timeout;
+		const signal = combineSignals([
+			options.signal,
+			timeout !== undefined ? AbortSignal.timeout(timeout) : undefined,
+		]);
+
 		return fetch(this.#buildUrl(url, options.query), {
 			method,
 			headers,
 			body: payload,
-			signal: options.signal,
+			signal,
 			credentials: options.credentials ?? this.#credentials,
 		});
 	}

package/src/index.ts

@@ -36,8 +36,18 @@ export {
 } from "./browser.js";
 export { component, onMount, onUnmount } from "./component.js";
 export { html, isTemplateResult } from "./html.js";
-export type { HttpClientOptions, HttpRequestOptions } from "./http.js";
-export { HttpClient, HttpError, http } from "./http.js";
+export type {
+	HttpClientOptions,
+	HttpRequestOptions,
+	HttpResult,
+} from "./http.js";
+export {
+	HttpClient,
+	HttpError,
+	http,
+	isAbortError,
+	isHttpError,
+} from "./http.js";
 export { hydrate } from "./hydrate.js";
 export {
 	batch,