@greendrake/vue-api 0.2.0 → 0.3.0

package/README.md

@@ -131,9 +131,11 @@ Retry re-runs the same call (the button reads "Trying..." until the retried atte
 Boot wiring, `configureApiUX({ errorSink?, goHome?, connectionSource? })`:
 
 - `errorSink: ErrorSink` — `(error, context?) => void`; receives `other`-kind failures and abnormal WebSocket closes (`WebSocketClosedError.isAbnormal`) for reporting. Nothing is reported without one.
-- `goHome` — the not-found toast's home action; default `location.assign('/')`. `@greendrake/vue-app` sets it to `router.push('/')`. `getGoHome()` returns the configured function for modules that navigate home outside a component.
+- `goHome` — the not-found toast's home action; default `location.assign('/')`. `getGoHome()` returns the configured function for modules that navigate home outside a component.
 - `connectionSource: ConnectionSource` — `{ readonly connected: boolean; onConnectionChange(listener) }`, read once when `useConnectivity` first materialises, so configure it before the store is first used. `@greendrake/rpc`'s `WsTransport` satisfies it as-is.
 
+`apiUXHooks` fills two `@greendrake/vue-app` `createSpaApp` options: `onRouter` sets `goHome` to `router.push('/')`, and `onBootError` shows a failed boot through `useExceptionState().fail`. Spread it into the options: `createSpaApp({ root, routes, ...apiUXHooks })`. The router is typed structurally (`{ push(to: string): unknown }`), so neither package depends on the other.
+
 ### Offline parking
 
 A non-silent call that fails with a `NetworkError` while `useConnectivity().offline` is true is parked instead of toasted, provided re-issuing it cannot double-apply: it carries no nonce (a cacheable read), or the transport rejected it before writing it (`WebSocketClosedError` with `inFlight === false`). A parked call releases its global loading slot — a scoped `pending` ref stays on, so the submitting control stays disabled — waits on `whenOnline()`, and re-runs once per reconnection. A nonce-carrying request that was on the wire when the socket went may have executed server-side with only its response lost, so it keeps the toast and the decision stays with the user.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@greendrake/vue-api",
-    "version": "0.2.0",
+    "version": "0.3.0",
     "description": "Vue binding of @greendrake/rpc: loading-state wiring, response cache, error-UX pipeline, silent calls, live bindings to server push",
     "license": "MIT",
     "author": "Eugene Greendrake <eugene@greendrake.nz>",
@@ -34,17 +34,17 @@
     },
     "prettier": "@greendrake/dev-config/prettier",
     "dependencies": {
-        "@greendrake/rpc": "0.2.0",
-        "@greendrake/ui": "0.2.0",
-        "@greendrake/util": "0.2.0",
-        "@greendrake/vue-kit": "0.2.0"
+        "@greendrake/rpc": "0.3.0",
+        "@greendrake/ui": "0.3.0",
+        "@greendrake/util": "0.3.0",
+        "@greendrake/vue-kit": "0.3.0"
     },
     "peerDependencies": {
         "pinia": "^3.0.4",
         "vue": "^3.5.34"
     },
     "devDependencies": {
-        "@greendrake/dev-config": "0.2.0",
+        "@greendrake/dev-config": "0.3.0",
         "pinia": "^3.0.4",
         "typescript": "6.0.3",
         "vue": "^3.5.34",

package/src/apiUXHooks.ts

@@ -0,0 +1,24 @@
+import { useExceptionState } from './exceptionState'
+import { configureApiUX } from './uxConfig'
+
+// The error-UX pipeline's half of @greendrake/vue-app's boot: spread into
+// createSpaApp's options. The router is typed by the one method used, so this
+// package takes no vue-router dependency.
+export const apiUXHooks = {
+    // The not-found toast's "To the home page" navigates through the app's
+    // router. Wired where the router is created rather than in an app's
+    // main.ts, so non-component modules (stores) can navigate home via
+    // getGoHome() without importing the app module — an import back-edge that
+    // would put main.ts inside a circular import and break HMR.
+    onRouter: (router: { push(to: string): unknown }): void => {
+        configureApiUX({
+            goHome: () => {
+                void router.push('/')
+            }
+        })
+    },
+    // A failed boot surfaces through the same toast as any other failure.
+    onBootError: (error: Error): void => {
+        useExceptionState().fail(error)
+    }
+}

package/src/main.ts

@@ -1,6 +1,7 @@
 export { ApiClient, UnacceptableResultError, type ApiClientOptions, type CallOptions } from './ApiClient'
 export { useExceptionState, classifyException, type ExceptionKind, type FailOptions } from './exceptionState'
 export { configureApiUX, getGoHome, type ConnectionSource, type ErrorSink } from './uxConfig'
+export { apiUXHooks } from './apiUXHooks'
 export { useConnectivity } from './connectivity'
 export { retryWhenOnline } from './retryWhenOnline'
 export { backgroundCall, bindLive, useLive } from './live'

package/src/uxConfig.ts

@@ -22,7 +22,7 @@ interface ApiUXConfig {
     // reporting — e.g. the visit subsystem's error channel.
     errorSink?: ErrorSink
     // Drives the not-found toast's "To the home page" action; typically
-    // router.push('/'). @greendrake/vue-app wires this automatically.
+    // router.push('/'). apiUXHooks wires it to a @greendrake/vue-app router.
     goHome?: () => void
     // Read once, when useConnectivity is first instantiated.
     connectionSource?: ConnectionSource