@c9up/aurora 0.1.7 → 0.1.9

package/README.md

@@ -24,7 +24,7 @@ providers: [
 
 ## Entry points
 
-- `@c9up/aurora` — main API: reactive primitives (`signal`/`effect`/`html`/`component`/`hydrate`) plus the client toolkit — `WebStorage`/`persistedSignal`, reactive browser signals (`prefersDark`/`online`/`windowSize`/…), SPA navigation (`navigate`/`queryParam`), `cookie`/`clipboard`/`share`, and the `HttpClient` fetch wrapper
+- `@c9up/aurora` — main API: reactive primitives (`signal`/`effect`/`html`/`component`/`hydrate`) plus the client toolkit — `WebStorage`/`persistedSignal`, reactive browser signals (`prefersDark`/`online`/`windowSize`/…), SPA navigation (`navigate`/`queryParam`), `cookie`/`clipboard`/`share`, the `HttpClient` fetch wrapper, `command()` (async action + reactive loading/data/error), and `form()` (reactive form controller; optional rune validation + rosetta i18n)
 - `@c9up/aurora/provider` — Ream IoC provider
 - `@c9up/aurora/services/main` — container service accessor
 - `@c9up/aurora/relay` — realtime adapter

package/dist/command.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `command()` — wrap an async task (typically an `HttpClient` call) with reactive
+ * `loading` / `data` / `error` signals plus `onSuccess` / `onFail` handlers and a
+ * `run(...args)` launcher, so call sites never write `then`/`catch` or
+ * `await`+try/catch.
+ *
+ * `run` is re-runnable with different arguments each time; the signals reflect
+ * the LATEST run. A superseded (slower) run that resolves after a newer one is
+ * silently dropped — it never overwrites the latest state — which makes
+ * re-running safe for search-as-you-type / retry. Node-free — part of the client
+ * barrel.
+ *
+ * ```js
+ * import { command, HttpClient, isHttpError } from '@c9up/aurora'
+ * const api = new HttpClient()
+ *
+ * const login = command((creds) => api.post('/auth/login', creds))
+ *   .onSuccess((u) => { user(u); redirect('/app') })
+ *   .onFail((e) => formError(isHttpError(e) ? e.data : 'Network error'))
+ *
+ * login.run(creds())          // launch — no try/catch
+ * // bind login.loading() for a spinner / disabled button
+ * ```
+ */
+import { type ReadSignal } from "./reactive.js";
+export interface Command<TArgs extends unknown[], TData> {
+    /** Latest successful result, or `null` before the first success / after `reset`. */
+    readonly data: ReadSignal<TData | null>;
+    /** Latest run's error, or `null` when none. */
+    readonly error: ReadSignal<unknown>;
+    /** Whether the latest run is in flight. */
+    readonly loading: ReadSignal<boolean>;
+    /** Register a success handler (chainable; multiple allowed). */
+    onSuccess(handler: (data: TData) => void): this;
+    /** Register a failure handler — receives the thrown error (chainable). */
+    onFail(handler: (error: unknown) => void): this;
+    /** Register a handler that runs after success OR failure (chainable). */
+    onSettled(handler: () => void): this;
+    /** Launch the task with `args`. Always resolves (errors route to `onFail`). */
+    run(...args: TArgs): Promise<void>;
+    /** Clear `data`/`error`/`loading` and invalidate any in-flight run. */
+    reset(): void;
+}
+/**
+ * Create a re-runnable {@link Command} around an async `task`. See the module
+ * doc for usage.
+ */
+export declare function command<TArgs extends unknown[], TData>(task: (...args: TArgs) => Promise<TData>): Command<TArgs, TData>;

package/dist/command.js

@@ -0,0 +1,93 @@
+/**
+ * `command()` — wrap an async task (typically an `HttpClient` call) with reactive
+ * `loading` / `data` / `error` signals plus `onSuccess` / `onFail` handlers and a
+ * `run(...args)` launcher, so call sites never write `then`/`catch` or
+ * `await`+try/catch.
+ *
+ * `run` is re-runnable with different arguments each time; the signals reflect
+ * the LATEST run. A superseded (slower) run that resolves after a newer one is
+ * silently dropped — it never overwrites the latest state — which makes
+ * re-running safe for search-as-you-type / retry. Node-free — part of the client
+ * barrel.
+ *
+ * ```js
+ * import { command, HttpClient, isHttpError } from '@c9up/aurora'
+ * const api = new HttpClient()
+ *
+ * const login = command((creds) => api.post('/auth/login', creds))
+ *   .onSuccess((u) => { user(u); redirect('/app') })
+ *   .onFail((e) => formError(isHttpError(e) ? e.data : 'Network error'))
+ *
+ * login.run(creds())          // launch — no try/catch
+ * // bind login.loading() for a spinner / disabled button
+ * ```
+ */
+import { signal } from "./reactive.js";
+class CommandRunner {
+    #task;
+    #data = signal(null);
+    #error = signal(null);
+    #loading = signal(false);
+    #onSuccess = [];
+    #onFail = [];
+    #onSettled = [];
+    #runId = 0;
+    data = this.#data;
+    error = this.#error;
+    loading = this.#loading;
+    constructor(task) {
+        this.#task = task;
+    }
+    onSuccess(handler) {
+        this.#onSuccess.push(handler);
+        return this;
+    }
+    onFail(handler) {
+        this.#onFail.push(handler);
+        return this;
+    }
+    onSettled(handler) {
+        this.#onSettled.push(handler);
+        return this;
+    }
+    reset() {
+        this.#runId++; // invalidate any in-flight run so it can't write back
+        this.#data(null);
+        this.#error(null);
+        this.#loading(false);
+    }
+    async run(...args) {
+        const id = ++this.#runId;
+        this.#loading(true);
+        this.#error(null);
+        try {
+            const result = await this.#task(...args);
+            if (id !== this.#runId)
+                return; // superseded by a newer run — drop
+            this.#data(result);
+            for (const handler of this.#onSuccess)
+                handler(result);
+        }
+        catch (error) {
+            if (id !== this.#runId)
+                return; // superseded — drop
+            this.#error(error);
+            for (const handler of this.#onFail)
+                handler(error);
+        }
+        finally {
+            if (id === this.#runId) {
+                this.#loading(false);
+                for (const handler of this.#onSettled)
+                    handler();
+            }
+        }
+    }
+}
+/**
+ * Create a re-runnable {@link Command} around an async `task`. See the module
+ * doc for usage.
+ */
+export function command(task) {
+    return new CommandRunner(task);
+}

package/dist/form.d.ts

@@ -0,0 +1,89 @@
+/**
+ * `form()` — a minimal reactive form controller: per-field `value` / `error` /
+ * `touched` signals, validation, and a submit driven by {@link command} (so the
+ * submit's `loading` / `error` are reactive too). Call sites bind the signals in
+ * `html\`\`` and never hand-roll field state or try/catch.
+ *
+ * Validation is OPTIONAL and **agnostic**: pass a `validate` function returning a
+ * `{ field: message }` map, OR any object with a `.validate(values)` method
+ * (e.g. a `@c9up/rune` schema) — aurora never imports a validator, it only
+ * duck-types `.validate`. With no `validate`, the form simply never reports field
+ * errors. Node-free — part of the client barrel.
+ *
+ * ```js
+ * import { form, HttpClient, isHttpError } from '@c9up/aurora'
+ * import { rules, schema } from '@c9up/rune'   // optional
+ * const api = new HttpClient()
+ *
+ * const f = form({
+ *   initial: { email: '', password: '' },
+ *   validate: schema({ email: rules.string().email(), password: rules.string().min(8) }),
+ *   submit: (values) => api.post('/auth/login', values),
+ * })
+ *   .onSuccess(() => redirect('/app'))
+ *   .onFail((e) => { if (isHttpError(e)) f.setErrors(e.data?.errors ?? {}) })
+ *
+ * const email = f.field('email')
+ * // <input value=${email.value} @input=${(e) => email.set(e.target.value)} @blur=${email.markTouched}>
+ * // <button ?disabled=${f.submitting} @click=${(e) => f.handleSubmit(e)}>
+ * ```
+ */
+import { type ReadSignal } from "./reactive.js";
+/** A field-keyed error map: `{ email: "Invalid", … }`. Absent key ⇒ no error. */
+export type FieldErrors<T> = Partial<Record<keyof T, string>>;
+/** Anything `.validate()`-shaped (a `@c9up/rune` schema satisfies this). */
+export interface FormSchema<T> {
+    validate(values: T): {
+        valid: boolean;
+        errors?: ReadonlyArray<{
+            field?: string;
+            message: string;
+        }>;
+    };
+}
+/** Validation source — a function, a schema-like object, or omitted. */
+export type FormValidate<T> = ((values: T) => FieldErrors<T>) | FormSchema<T>;
+export interface FormOptions<T> {
+    /** Initial field values; its keys define the form's fields. */
+    initial: T;
+    /** The submit task (wrapped in a {@link command}). */
+    submit: (values: T) => Promise<unknown>;
+    /** Optional, agnostic validation (function OR `.validate`-shaped object). */
+    validate?: FormValidate<T>;
+}
+/** A single field's reactive handles + setters. */
+export interface FormField<V> {
+    readonly value: ReadSignal<V>;
+    readonly error: ReadSignal<string | null>;
+    readonly touched: ReadSignal<boolean>;
+    set(value: V): void;
+    markTouched(): void;
+}
+export interface Form<T> {
+    readonly values: ReadSignal<T>;
+    readonly errors: ReadSignal<FieldErrors<T>>;
+    /** Whether the last validation found no errors. */
+    readonly valid: ReadSignal<boolean>;
+    /** Whether the submit is in flight (the submit command's loading). */
+    readonly submitting: ReadSignal<boolean>;
+    /** The submit command's last error. */
+    readonly submitError: ReadSignal<unknown>;
+    field<K extends keyof T>(key: K): FormField<T[K]>;
+    set<K extends keyof T>(key: K, value: T[K]): void;
+    /** Run validation now, populate `errors`, and return whether it passed. */
+    validate(): boolean;
+    /** Validate then submit (no-op if invalid). Calls `event.preventDefault()`. */
+    handleSubmit(event?: {
+        preventDefault(): void;
+    }): Promise<void>;
+    /** Merge in errors (e.g. server-side field errors from `HttpError.data`). */
+    setErrors(errors: FieldErrors<T>): void;
+    /** Reset values to `initial` and clear errors / touched / submit state. */
+    reset(): void;
+    /** Submit success handler (chainable) — receives the resolved value. */
+    onSuccess(handler: (data: unknown) => void): this;
+    /** Submit failure handler (chainable) — receives the thrown error. */
+    onFail(handler: (error: unknown) => void): this;
+}
+/** Create a reactive {@link Form} controller. See the module doc for usage. */
+export declare function form<T>(options: FormOptions<T>): Form<T>;

package/dist/form.js

@@ -0,0 +1,130 @@
+/**
+ * `form()` — a minimal reactive form controller: per-field `value` / `error` /
+ * `touched` signals, validation, and a submit driven by {@link command} (so the
+ * submit's `loading` / `error` are reactive too). Call sites bind the signals in
+ * `html\`\`` and never hand-roll field state or try/catch.
+ *
+ * Validation is OPTIONAL and **agnostic**: pass a `validate` function returning a
+ * `{ field: message }` map, OR any object with a `.validate(values)` method
+ * (e.g. a `@c9up/rune` schema) — aurora never imports a validator, it only
+ * duck-types `.validate`. With no `validate`, the form simply never reports field
+ * errors. Node-free — part of the client barrel.
+ *
+ * ```js
+ * import { form, HttpClient, isHttpError } from '@c9up/aurora'
+ * import { rules, schema } from '@c9up/rune'   // optional
+ * const api = new HttpClient()
+ *
+ * const f = form({
+ *   initial: { email: '', password: '' },
+ *   validate: schema({ email: rules.string().email(), password: rules.string().min(8) }),
+ *   submit: (values) => api.post('/auth/login', values),
+ * })
+ *   .onSuccess(() => redirect('/app'))
+ *   .onFail((e) => { if (isHttpError(e)) f.setErrors(e.data?.errors ?? {}) })
+ *
+ * const email = f.field('email')
+ * // <input value=${email.value} @input=${(e) => email.set(e.target.value)} @blur=${email.markTouched}>
+ * // <button ?disabled=${f.submitting} @click=${(e) => f.handleSubmit(e)}>
+ * ```
+ */
+import { command } from "./command.js";
+import { memo, signal } from "./reactive.js";
+/** Normalize any validation source into a field-error map. */
+function computeErrors(validate, values) {
+    if (!validate)
+        return {};
+    if (typeof validate === "function")
+        return validate(values);
+    const result = validate.validate(values);
+    if (result.valid)
+        return {};
+    const errors = {};
+    for (const issue of result.errors ?? []) {
+        if (issue.field && !(issue.field in errors)) {
+            errors[issue.field] = issue.message;
+        }
+    }
+    // Boundary: a schema's errors are string-keyed and it doesn't know `keyof T`,
+    // so narrow the validated key space to the form's field type here.
+    return errors;
+}
+class FormController {
+    #initial;
+    #validate;
+    #values;
+    #errors = signal({});
+    #touched = signal(new Set());
+    #command;
+    values;
+    errors = this.#errors;
+    valid;
+    submitting;
+    submitError;
+    constructor(options) {
+        this.#initial = { ...options.initial };
+        this.#validate = options.validate;
+        this.#values = signal({ ...options.initial });
+        this.values = this.#values;
+        this.#command = command((values) => options.submit(values));
+        this.submitting = this.#command.loading;
+        this.submitError = this.#command.error;
+        this.valid = memo(() => Object.values(this.#errors()).every((message) => !message));
+    }
+    field(key) {
+        return {
+            value: memo(() => this.#values()[key]),
+            error: memo(() => this.#errors()[key] ?? null),
+            touched: memo(() => this.#touched().has(String(key))),
+            set: (value) => this.set(key, value),
+            markTouched: () => this.#markTouched(key),
+        };
+    }
+    set(key, value) {
+        const next = { ...this.#values() };
+        next[key] = value;
+        this.#values(next);
+        // Clear a stale error for this field as the user edits it.
+        if (this.#errors()[key] !== undefined) {
+            const errors = { ...this.#errors() };
+            delete errors[key];
+            this.#errors(errors);
+        }
+    }
+    validate() {
+        const errors = computeErrors(this.#validate, this.#values());
+        this.#errors(errors);
+        return Object.values(errors).every((message) => !message);
+    }
+    async handleSubmit(event) {
+        event?.preventDefault();
+        this.#touched(new Set(Object.keys(this.#values())));
+        if (!this.validate())
+            return;
+        await this.#command.run(this.#values());
+    }
+    setErrors(errors) {
+        this.#errors({ ...this.#errors(), ...errors });
+    }
+    reset() {
+        this.#values({ ...this.#initial });
+        this.#errors({});
+        this.#touched(new Set());
+        this.#command.reset();
+    }
+    onSuccess(handler) {
+        this.#command.onSuccess(handler);
+        return this;
+    }
+    onFail(handler) {
+        this.#command.onFail(handler);
+        return this;
+    }
+    #markTouched(key) {
+        this.#touched(new Set(this.#touched()).add(String(key)));
+    }
+}
+/** Create a reactive {@link Form} controller. See the module doc for usage. */
+export function form(options) {
+    return new FormController(options);
+}

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

@@ -1,9 +1,13 @@
 export type { CookieOptions, PersistedSignalOptions, ShareData, StorageArea, WebStorageOptions, WindowSize, } from "./browser.js";
 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 type { Command } from "./command.js";
+export { command } from "./command.js";
 export { component, onMount, onUnmount } from "./component.js";
+export type { FieldErrors, Form, FormField, FormOptions, FormSchema, FormValidate, } from "./form.js";
+export { form } from "./form.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,9 @@
 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 { command } from "./command.js";
 export { component, onMount, onUnmount } from "./component.js";
+export { form } from "./form.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.9",
   "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/command.ts

@@ -0,0 +1,119 @@
+/**
+ * `command()` — wrap an async task (typically an `HttpClient` call) with reactive
+ * `loading` / `data` / `error` signals plus `onSuccess` / `onFail` handlers and a
+ * `run(...args)` launcher, so call sites never write `then`/`catch` or
+ * `await`+try/catch.
+ *
+ * `run` is re-runnable with different arguments each time; the signals reflect
+ * the LATEST run. A superseded (slower) run that resolves after a newer one is
+ * silently dropped — it never overwrites the latest state — which makes
+ * re-running safe for search-as-you-type / retry. Node-free — part of the client
+ * barrel.
+ *
+ * ```js
+ * import { command, HttpClient, isHttpError } from '@c9up/aurora'
+ * const api = new HttpClient()
+ *
+ * const login = command((creds) => api.post('/auth/login', creds))
+ *   .onSuccess((u) => { user(u); redirect('/app') })
+ *   .onFail((e) => formError(isHttpError(e) ? e.data : 'Network error'))
+ *
+ * login.run(creds())          // launch — no try/catch
+ * // bind login.loading() for a spinner / disabled button
+ * ```
+ */
+
+import { type ReadSignal, signal } from "./reactive.js";
+
+export interface Command<TArgs extends unknown[], TData> {
+	/** Latest successful result, or `null` before the first success / after `reset`. */
+	readonly data: ReadSignal<TData | null>;
+	/** Latest run's error, or `null` when none. */
+	readonly error: ReadSignal<unknown>;
+	/** Whether the latest run is in flight. */
+	readonly loading: ReadSignal<boolean>;
+	/** Register a success handler (chainable; multiple allowed). */
+	onSuccess(handler: (data: TData) => void): this;
+	/** Register a failure handler — receives the thrown error (chainable). */
+	onFail(handler: (error: unknown) => void): this;
+	/** Register a handler that runs after success OR failure (chainable). */
+	onSettled(handler: () => void): this;
+	/** Launch the task with `args`. Always resolves (errors route to `onFail`). */
+	run(...args: TArgs): Promise<void>;
+	/** Clear `data`/`error`/`loading` and invalidate any in-flight run. */
+	reset(): void;
+}
+
+class CommandRunner<TArgs extends unknown[], TData>
+	implements Command<TArgs, TData>
+{
+	readonly #task: (...args: TArgs) => Promise<TData>;
+	readonly #data = signal<TData | null>(null);
+	readonly #error = signal<unknown>(null);
+	readonly #loading = signal(false);
+	readonly #onSuccess: Array<(data: TData) => void> = [];
+	readonly #onFail: Array<(error: unknown) => void> = [];
+	readonly #onSettled: Array<() => void> = [];
+	#runId = 0;
+
+	readonly data: ReadSignal<TData | null> = this.#data;
+	readonly error: ReadSignal<unknown> = this.#error;
+	readonly loading: ReadSignal<boolean> = this.#loading;
+
+	constructor(task: (...args: TArgs) => Promise<TData>) {
+		this.#task = task;
+	}
+
+	onSuccess(handler: (data: TData) => void): this {
+		this.#onSuccess.push(handler);
+		return this;
+	}
+
+	onFail(handler: (error: unknown) => void): this {
+		this.#onFail.push(handler);
+		return this;
+	}
+
+	onSettled(handler: () => void): this {
+		this.#onSettled.push(handler);
+		return this;
+	}
+
+	reset(): void {
+		this.#runId++; // invalidate any in-flight run so it can't write back
+		this.#data(null);
+		this.#error(null);
+		this.#loading(false);
+	}
+
+	async run(...args: TArgs): Promise<void> {
+		const id = ++this.#runId;
+		this.#loading(true);
+		this.#error(null);
+		try {
+			const result = await this.#task(...args);
+			if (id !== this.#runId) return; // superseded by a newer run — drop
+			this.#data(result);
+			for (const handler of this.#onSuccess) handler(result);
+		} catch (error) {
+			if (id !== this.#runId) return; // superseded — drop
+			this.#error(error);
+			for (const handler of this.#onFail) handler(error);
+		} finally {
+			if (id === this.#runId) {
+				this.#loading(false);
+				for (const handler of this.#onSettled) handler();
+			}
+		}
+	}
+}
+
+/**
+ * Create a re-runnable {@link Command} around an async `task`. See the module
+ * doc for usage.
+ */
+export function command<TArgs extends unknown[], TData>(
+	task: (...args: TArgs) => Promise<TData>,
+): Command<TArgs, TData> {
+	return new CommandRunner(task);
+}

package/src/form.ts

@@ -0,0 +1,203 @@
+/**
+ * `form()` — a minimal reactive form controller: per-field `value` / `error` /
+ * `touched` signals, validation, and a submit driven by {@link command} (so the
+ * submit's `loading` / `error` are reactive too). Call sites bind the signals in
+ * `html\`\`` and never hand-roll field state or try/catch.
+ *
+ * Validation is OPTIONAL and **agnostic**: pass a `validate` function returning a
+ * `{ field: message }` map, OR any object with a `.validate(values)` method
+ * (e.g. a `@c9up/rune` schema) — aurora never imports a validator, it only
+ * duck-types `.validate`. With no `validate`, the form simply never reports field
+ * errors. Node-free — part of the client barrel.
+ *
+ * ```js
+ * import { form, HttpClient, isHttpError } from '@c9up/aurora'
+ * import { rules, schema } from '@c9up/rune'   // optional
+ * const api = new HttpClient()
+ *
+ * const f = form({
+ *   initial: { email: '', password: '' },
+ *   validate: schema({ email: rules.string().email(), password: rules.string().min(8) }),
+ *   submit: (values) => api.post('/auth/login', values),
+ * })
+ *   .onSuccess(() => redirect('/app'))
+ *   .onFail((e) => { if (isHttpError(e)) f.setErrors(e.data?.errors ?? {}) })
+ *
+ * const email = f.field('email')
+ * // <input value=${email.value} @input=${(e) => email.set(e.target.value)} @blur=${email.markTouched}>
+ * // <button ?disabled=${f.submitting} @click=${(e) => f.handleSubmit(e)}>
+ * ```
+ */
+
+import { command } from "./command.js";
+import { memo, type ReadSignal, signal } from "./reactive.js";
+
+/** A field-keyed error map: `{ email: "Invalid", … }`. Absent key ⇒ no error. */
+export type FieldErrors<T> = Partial<Record<keyof T, string>>;
+
+/** Anything `.validate()`-shaped (a `@c9up/rune` schema satisfies this). */
+export interface FormSchema<T> {
+	validate(values: T): {
+		valid: boolean;
+		errors?: ReadonlyArray<{ field?: string; message: string }>;
+	};
+}
+
+/** Validation source — a function, a schema-like object, or omitted. */
+export type FormValidate<T> = ((values: T) => FieldErrors<T>) | FormSchema<T>;
+
+export interface FormOptions<T> {
+	/** Initial field values; its keys define the form's fields. */
+	initial: T;
+	/** The submit task (wrapped in a {@link command}). */
+	submit: (values: T) => Promise<unknown>;
+	/** Optional, agnostic validation (function OR `.validate`-shaped object). */
+	validate?: FormValidate<T>;
+}
+
+/** A single field's reactive handles + setters. */
+export interface FormField<V> {
+	readonly value: ReadSignal<V>;
+	readonly error: ReadSignal<string | null>;
+	readonly touched: ReadSignal<boolean>;
+	set(value: V): void;
+	markTouched(): void;
+}
+
+export interface Form<T> {
+	readonly values: ReadSignal<T>;
+	readonly errors: ReadSignal<FieldErrors<T>>;
+	/** Whether the last validation found no errors. */
+	readonly valid: ReadSignal<boolean>;
+	/** Whether the submit is in flight (the submit command's loading). */
+	readonly submitting: ReadSignal<boolean>;
+	/** The submit command's last error. */
+	readonly submitError: ReadSignal<unknown>;
+	field<K extends keyof T>(key: K): FormField<T[K]>;
+	set<K extends keyof T>(key: K, value: T[K]): void;
+	/** Run validation now, populate `errors`, and return whether it passed. */
+	validate(): boolean;
+	/** Validate then submit (no-op if invalid). Calls `event.preventDefault()`. */
+	handleSubmit(event?: { preventDefault(): void }): Promise<void>;
+	/** Merge in errors (e.g. server-side field errors from `HttpError.data`). */
+	setErrors(errors: FieldErrors<T>): void;
+	/** Reset values to `initial` and clear errors / touched / submit state. */
+	reset(): void;
+	/** Submit success handler (chainable) — receives the resolved value. */
+	onSuccess(handler: (data: unknown) => void): this;
+	/** Submit failure handler (chainable) — receives the thrown error. */
+	onFail(handler: (error: unknown) => void): this;
+}
+
+/** Normalize any validation source into a field-error map. */
+function computeErrors<T>(
+	validate: FormValidate<T> | undefined,
+	values: T,
+): FieldErrors<T> {
+	if (!validate) return {};
+	if (typeof validate === "function") return validate(values);
+	const result = validate.validate(values);
+	if (result.valid) return {};
+	const errors: Record<string, string> = {};
+	for (const issue of result.errors ?? []) {
+		if (issue.field && !(issue.field in errors)) {
+			errors[issue.field] = issue.message;
+		}
+	}
+	// Boundary: a schema's errors are string-keyed and it doesn't know `keyof T`,
+	// so narrow the validated key space to the form's field type here.
+	return errors as FieldErrors<T>;
+}
+
+class FormController<T> implements Form<T> {
+	readonly #initial: T;
+	readonly #validate?: FormValidate<T>;
+	readonly #values: ReturnType<typeof signal<T>>;
+	readonly #errors = signal<FieldErrors<T>>({});
+	readonly #touched = signal<ReadonlySet<string>>(new Set());
+	readonly #command: ReturnType<typeof command<[T], unknown>>;
+
+	readonly values: ReadSignal<T>;
+	readonly errors: ReadSignal<FieldErrors<T>> = this.#errors;
+	readonly valid: ReadSignal<boolean>;
+	readonly submitting: ReadSignal<boolean>;
+	readonly submitError: ReadSignal<unknown>;
+
+	constructor(options: FormOptions<T>) {
+		this.#initial = { ...options.initial };
+		this.#validate = options.validate;
+		this.#values = signal<T>({ ...options.initial });
+		this.values = this.#values;
+		this.#command = command((values: T) => options.submit(values));
+		this.submitting = this.#command.loading;
+		this.submitError = this.#command.error;
+		this.valid = memo(() =>
+			Object.values(this.#errors()).every((message) => !message),
+		);
+	}
+
+	field<K extends keyof T>(key: K): FormField<T[K]> {
+		return {
+			value: memo(() => this.#values()[key]),
+			error: memo(() => this.#errors()[key] ?? null),
+			touched: memo(() => this.#touched().has(String(key))),
+			set: (value: T[K]) => this.set(key, value),
+			markTouched: () => this.#markTouched(key),
+		};
+	}
+
+	set<K extends keyof T>(key: K, value: T[K]): void {
+		const next = { ...this.#values() };
+		next[key] = value;
+		this.#values(next);
+		// Clear a stale error for this field as the user edits it.
+		if (this.#errors()[key] !== undefined) {
+			const errors = { ...this.#errors() };
+			delete errors[key];
+			this.#errors(errors);
+		}
+	}
+
+	validate(): boolean {
+		const errors = computeErrors(this.#validate, this.#values());
+		this.#errors(errors);
+		return Object.values(errors).every((message) => !message);
+	}
+
+	async handleSubmit(event?: { preventDefault(): void }): Promise<void> {
+		event?.preventDefault();
+		this.#touched(new Set(Object.keys(this.#values() as object)));
+		if (!this.validate()) return;
+		await this.#command.run(this.#values());
+	}
+
+	setErrors(errors: FieldErrors<T>): void {
+		this.#errors({ ...this.#errors(), ...errors });
+	}
+
+	reset(): void {
+		this.#values({ ...this.#initial });
+		this.#errors({});
+		this.#touched(new Set());
+		this.#command.reset();
+	}
+
+	onSuccess(handler: (data: unknown) => void): this {
+		this.#command.onSuccess(handler);
+		return this;
+	}
+
+	onFail(handler: (error: unknown) => void): this {
+		this.#command.onFail(handler);
+		return this;
+	}
+
+	#markTouched(key: keyof T): void {
+		this.#touched(new Set(this.#touched()).add(String(key)));
+	}
+}
+
+/** Create a reactive {@link Form} controller. See the module doc for usage. */
+export function form<T>(options: FormOptions<T>): Form<T> {
+	return new FormController(options);
+}

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

@@ -34,10 +34,31 @@ export {
 	WebStorage,
 	windowSize,
 } from "./browser.js";
+export type { Command } from "./command.js";
+export { command } from "./command.js";
 export { component, onMount, onUnmount } from "./component.js";
+export type {
+	FieldErrors,
+	Form,
+	FormField,
+	FormOptions,
+	FormSchema,
+	FormValidate,
+} from "./form.js";
+export { form } from "./form.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,