@jarenjs/app 0.34.2 → 0.43.1

package/README.md

@@ -94,7 +94,7 @@ effects: {
 }
 ```
 
-The helper aborts a slot's in-flight predecessor (`mode: "switch"`, the default — `"exhaust"`, `"concat"` and `"parallel"` pick the other per-slot concurrency semantics), dispatches `done` with `{ id, result }` on resolve and `fail ?? done` with `{ id, error }` (a string) on failure, and dispatches nothing for an abort. The abort is only an optimization — an aborted request may already have resolved — so the state-side id guard is the guarantee: out-of-order and polling responses are rejected by construction. The handler exposes `cancel(slot)`/`cancelAll()`/`dispose()`; `app.destroy()` disposes it automatically. The full convention, with a runnable worked example the test suite executes verbatim, is [docs/TASKS.md](docs/TASKS.md).
+The helper aborts a slot's in-flight predecessor (`mode: "switch"`, the default — `"exhaust"`, `"concat"` and `"parallel"` pick the other per-slot concurrency semantics), dispatches `done` with `{ id, result }` on resolve and `fail ?? done` with `{ id, error }` on failure — `error` a string by default, or the JSON an optional `projectError(err, props)` returns (the door for a structured HTTP failure: status, code, safe details; anything non-JSON falls back to the string) — and dispatches nothing for an abort. The abort is only an optimization — an aborted request may already have resolved — so the state-side id guard is the guarantee: out-of-order and polling responses are rejected by construction. The handler exposes `cancel(slot)`/`cancelAll()`/`dispose()`; `app.destroy()` disposes it automatically. The full convention, with a runnable worked example the test suite executes verbatim, is [docs/TASKS.md](docs/TASKS.md).
 
 ## One FIFO queue, observable transactions
 
@@ -186,7 +186,7 @@ renderToString(createApp(doc).getVnode());
 
 ## API
 
-`createApp(appDoc, options)` → `{ dispatch(name, payload?), getState(), getVnode(), render(), subscribe(listener), observe(observer), stop(), destroy() }`
+`createApp(appDoc, options)` → `{ dispatch(name, payload?), getState(), setState(next), getVnode(), render(), subscribe(listener), observe(observer), stop(), destroy() }`
 
 Also exported: `compileActions`, `compileSubs`, `createFormView`, `createFormActions`, `formEventFields`, `createTaskEffect`, `createFocusEffect`, `createTransactionLog`, `createSplitterWidget`, `createDocStore`, `encodeShare`, `decodeShare`, and the error classes (`AppCompileError`, `AppRuntimeError`, `HostValueError`, `toError`, `APP_CODES`).
 

package/dist/types/tasks.d.ts

@@ -9,8 +9,8 @@
  * its dispatch may already be queued, so a host that only aborts is
  * still wrong; the state-side guard is the guarantee.
  *
- * No timers, no state beyond the per-slot records, no dependencies
- * (`AbortController` is platform).
+ * No timers, no state beyond the per-slot records, no third-party
+ * dependencies (`AbortController` is platform).
  */
 export type TaskRun = (props: any, signal: AbortSignal) => any | PromiseLike<any>;
 export type TaskMode = 'switch' | 'exhaust' | 'concat' | 'parallel';
@@ -20,6 +20,19 @@ export type TaskEffectOptions = {
      * (default `"switch"`).
      */
     mode?: TaskMode;
+    /**
+     * - Project
+     * a NON-abort rejection into the JSON `error` member of the `{ id,
+     * error }` settlement payload — the door for a structured HTTP failure
+     * (status, code, safe details) that the default string projection would
+     * flatten. Receives the rejection value and the effect props verbatim.
+     * An `AbortError` never reaches it (cancellation dispatches nothing).
+     * Its result must be JSON: a projector that throws, returns `undefined`
+     * or returns a value JSON cannot carry (a host object, a function, a
+     * cycle ...) falls back to the string, so settlement stays total and no
+     * host object enters state through it.
+     */
+    projectError?: (err: unknown, props: any) => any;
 };
 export type TaskEffect = ((props: any, dispatch: (name: string, payload?: any) => void) => void) & {
     cancel: (slot?: string) => void;
@@ -60,6 +73,16 @@ export type TaskEffect = ((props: any, dispatch: (name: string, payload?: any) =
  * @typedef {Object} TaskEffectOptions
  * @property {TaskMode} [mode] - The per-slot concurrency mode
  *   (default `"switch"`).
+ * @property {(err: unknown, props: any) => any} [projectError] - Project
+ *   a NON-abort rejection into the JSON `error` member of the `{ id,
+ *   error }` settlement payload — the door for a structured HTTP failure
+ *   (status, code, safe details) that the default string projection would
+ *   flatten. Receives the rejection value and the effect props verbatim.
+ *   An `AbortError` never reaches it (cancellation dispatches nothing).
+ *   Its result must be JSON: a projector that throws, returns `undefined`
+ *   or returns a value JSON cannot carry (a host object, a function, a
+ *   cycle ...) falls back to the string, so settlement stays total and no
+ *   host object enters state through it.
  */
 /**
  * The effect handler returned by {@link createTaskEffect}, with its
@@ -93,8 +116,10 @@ export type TaskEffect = ((props: any, dispatch: (name: string, payload?: any) =
  * (`err.name === "AbortError"`) dispatches **nothing** — a superseded
  * task is dead by design, its successor's dispatch carries the story;
  * any other rejection dispatches `fail ?? done` with `{ id, error }`
- * where `error` is a string, never an Error object — JSON only crosses
- * the boundary. After `dispose()` no settlement dispatches anything.
+ * where `error` is a string — or, with `options.projectError`, the JSON
+ * value the projector returned — never an Error object: JSON only
+ * crosses the boundary. After `dispose()` no settlement dispatches
+ * anything.
  * A malformed `id`/`done`/`fail`/`slot` is a host programming error:
  * the handler throws a `TypeError`, which the loop reports as `JA2007`.
  * Settlement is TOTAL for every rejection value (hostile accessors,

package/docs/APP-FORMAT.md

@@ -647,6 +647,29 @@ automatically by `app.destroy()`). `run` is invoked through a uniform
 promise boundary: a synchronous throw and a non-promise return settle
 through the same path as a rejection/resolution.
 
+### 9.3 Structured failure — `projectError`
+
+By default a non-abort rejection settles as `{ id, error }` with `error`
+a **string**. That flattens what an HTTP host knows about a failure —
+status, a stable error code, safe details — so `createTaskEffect` takes
+an optional `projectError(err, props) => JSON` that produces the `error`
+member instead. The rules that keep the door narrow:
+
+- an `AbortError` never reaches the projector — cancellation dispatches
+  nothing, as before;
+- the projector receives the rejection value and the effect props
+  verbatim (so it can name the operation the failure belongs to);
+- its result must be JSON. A projector that throws, returns `undefined`
+  (declines) or returns a value JSON cannot carry — an `Error`, a
+  `Response`, a function, a class instance, a cycle, a non-finite number
+  — falls back to the string projection. Settlement therefore stays
+  total, and no host object enters state through this path;
+- a non-function `projectError` is a `TypeError` at construction (a host
+  programming error).
+
+The completion action stores whatever it is handed; the state schema is
+where the projected shape is pinned.
+
 ## 10. Errors
 
 ### 10.1 The host-failure normalization policy

package/docs/TASKS.md

@@ -105,8 +105,10 @@ ignored — the double-click-safe commit mode), `"concat"` (starts queue
 and run strictly in order) or `"parallel"` (APP-FORMAT §9.2). The
 handler carries the host-side controls `cancel(slot)`, `cancelAll()`
 and `dispose()` — after `dispose()` (which `app.destroy()` calls
-automatically) no late settlement can dispatch. The effect-props
-convention (all JSON):
+automatically) no late settlement can dispatch. `options.projectError`
+opens the structured-failure door: an HTTP host can settle `{ id,
+error: { status, code, ... } }` instead of a flattened string
+(APP-FORMAT §9.3). The effect-props convention (all JSON):
 
 | Prop | | Meaning |
 |---|---|---|
@@ -123,7 +125,7 @@ Settlement semantics, exactly:
 | start | The slot's in-flight controller (if any) is aborted; a fresh one is stored; `run(props, signal)` is called. |
 | resolve | `dispatch(done, { id, result })`. |
 | reject, `err.name === "AbortError"` | **Nothing.** A superseded task is dead by design; its successor's dispatch carries the story. |
-| reject, anything else | `dispatch(fail ?? done, { id, error })` — `error` is a **string**, never an Error object; JSON only crosses the boundary. |
+| reject, anything else | `dispatch(fail ?? done, { id, error })` — `error` is a **string** by default, or the JSON value `options.projectError(err, props)` returned (APP-FORMAT §9.3); never an Error object — JSON only crosses the boundary. A projector that throws, declines (`undefined`) or returns non-JSON falls back to the string. |
 | settle | The task's controller is released; a `concat` slot starts its next queued task. |
 | after `dispose()` | **Nothing** — a late settlement can no longer dispatch. |
 | malformed `id`/`done`/`fail`/`slot` | A `TypeError` from the handler — a host programming error, reported by the loop as `JA2007`. |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/app",
   "private": false,
-  "version": "0.34.2",
+  "version": "0.43.1",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -50,8 +50,8 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.34.2",
-    "@jarenjs/json": "^0.34.2",
-    "@jarenjs/view": "^0.34.2"
+    "@jarenjs/core": "^0.43.1",
+    "@jarenjs/json": "^0.43.1",
+    "@jarenjs/view": "^0.43.1"
   }
 }

package/src/tasks.js

@@ -10,10 +10,12 @@
  * its dispatch may already be queued, so a host that only aborts is
  * still wrong; the state-side guard is the guarantee.
  *
- * No timers, no state beyond the per-slot records, no dependencies
- * (`AbortController` is platform).
+ * No timers, no state beyond the per-slot records, no third-party
+ * dependencies (`AbortController` is platform).
  */
 
+import { isJsonValue } from '@jarenjs/core/object';
+
 import { toError, isErrorSafely, safeErrorMessage } from './errors.js';
 
 /**
@@ -52,6 +54,31 @@ function rejectionText(err) {
   return toError(err).message;
 }
 
+/**
+ * The `{ id, error }` payload for a non-abort rejection: the host's
+ * `projectError` result when it produced JSON, the string projection
+ * otherwise. TOTAL like everything on this path — a projector that
+ * throws, returns `undefined` (declines) or returns anything JSON cannot
+ * carry (an `Error`, a `Response`, a function, a cycle ...) falls back to
+ * the string, so no host object crosses into state through this door.
+ * @param {((err: unknown, props: any) => any) | null} projectError
+ * @param {unknown} err
+ * @param {any} props
+ * @returns {any}
+ */
+function rejectionPayload(projectError, err, props) {
+  if (projectError !== null) {
+    try {
+      const projected = projectError(err, props);
+      if (projected !== undefined && isJsonValue(projected)) return projected;
+    }
+    catch {
+      // fall through to the string projection
+    }
+  }
+  return rejectionText(err);
+}
+
 /**
  * The host's task function, typically wrapping `fetch`. A synchronous
  * return is allowed — the effect settles every result through one
@@ -88,6 +115,16 @@ function rejectionText(err) {
  * @typedef {Object} TaskEffectOptions
  * @property {TaskMode} [mode] - The per-slot concurrency mode
  *   (default `"switch"`).
+ * @property {(err: unknown, props: any) => any} [projectError] - Project
+ *   a NON-abort rejection into the JSON `error` member of the `{ id,
+ *   error }` settlement payload — the door for a structured HTTP failure
+ *   (status, code, safe details) that the default string projection would
+ *   flatten. Receives the rejection value and the effect props verbatim.
+ *   An `AbortError` never reaches it (cancellation dispatches nothing).
+ *   Its result must be JSON: a projector that throws, returns `undefined`
+ *   or returns a value JSON cannot carry (a host object, a function, a
+ *   cycle ...) falls back to the string, so settlement stays total and no
+ *   host object enters state through it.
  */
 
 /**
@@ -123,8 +160,10 @@ function rejectionText(err) {
  * (`err.name === "AbortError"`) dispatches **nothing** — a superseded
  * task is dead by design, its successor's dispatch carries the story;
  * any other rejection dispatches `fail ?? done` with `{ id, error }`
- * where `error` is a string, never an Error object — JSON only crosses
- * the boundary. After `dispose()` no settlement dispatches anything.
+ * where `error` is a string — or, with `options.projectError`, the JSON
+ * value the projector returned — never an Error object: JSON only
+ * crosses the boundary. After `dispose()` no settlement dispatches
+ * anything.
  * A malformed `id`/`done`/`fail`/`slot` is a host programming error:
  * the handler throws a `TypeError`, which the loop reports as `JA2007`.
  * Settlement is TOTAL for every rejection value (hostile accessors,
@@ -161,6 +200,10 @@ export function createTaskEffect(run, options = {}) {
   if (mode !== 'switch' && mode !== 'exhaust' && mode !== 'concat' && mode !== 'parallel') {
     throw new TypeError(`createTaskEffect: unknown mode '${String(mode)}'`);
   }
+  const projectError = options.projectError ?? null;
+  if (projectError !== null && typeof projectError !== 'function') {
+    throw new TypeError('createTaskEffect: "projectError" must be a function');
+  }
 
   /**
    * Per-slot bookkeeping: the in-flight controllers and, for `concat`,
@@ -221,7 +264,7 @@ export function createTaskEffect(run, options = {}) {
         // still dispatches by contract, and only the state-side id
         // guard rejects it. A hostile value never breaks settlement.
         if (safeName(err) === 'AbortError') return;
-        const error = rejectionText(err);
+        const error = rejectionPayload(projectError, err, props);
         // a settlement dispatch that itself throws (a rethrowing error
         // sink surfacing at the dispatch boundary) must not become an
         // unobservable promise rejection: it is re-raised on its own