@greendrake/vue-api 0.2.0 → 0.4.0

package/README.md

@@ -18,10 +18,10 @@ One module declares the typed method map, builds the transport and exports the c
 // src/api.ts
 import { HttpTransport } from '@greendrake/rpc'
 import { ApiClient } from '@greendrake/vue-api'
-import type { Host, ListResult, PageArgs, Vlan } from './types'
+import type { Host, HostQuery, ListResult, Vlan } from './types'
 
 export interface Methods {
-    'host.list': (query: PageArgs) => ListResult<Host>
+    'host.list': (query: HostQuery) => ListResult<Host>
     'host.get': (id: number) => Host
     'host.update': (record: { id: number } & Partial<Host>) => Host
     'host.delete': (args: { id: number }) => void
@@ -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` is `{ onRouter(router), onBootError(error) }`, for an app bootstrap that offers those two hooks: `onRouter` sets `goHome` to `router.push('/')` the moment the router exists, and `onBootError` shows a failed boot through `useExceptionState().fail`. The router is typed structurally (`{ push(to: string): unknown }`), so this package takes no router dependency.
+
 ### 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.
@@ -180,8 +182,8 @@ The mechanism — relevance, `apply` versus `resync`, the reconnect re-read, coa
 - Its failure neither interrupts nor vanishes. A `NotFoundError` is dropped (the entity went away while the socket was down; the next navigation says so), a `NetworkError` is dropped (the socket went again mid-read, and the binding's own reconnect rule re-reads when it returns), and anything else goes to the `errorSink` configured through `configureApiUX` — reported, never toasted.
 - It must read past a response cache the missed pushes would have invalidated: invalidate the entries the read would hit, then read, so the stale entry is repaired rather than stepped around.
 
-`backgroundCall` also serves a table's loader, which is where a panel's re-read actually calls the API — see `@greendrake/ui-data`'s loader contract:
+`backgroundCall` also serves any loader told whether anybody asked for its load — a table re-reading after a push, say, which is where a panel's re-read actually calls the API:
 
 ```ts
-const loader = listLoader((args, background) => api.call('admin.thread.list', [args], backgroundCall(background)))
+const load = (args: ListArgs, background: boolean) => api.call('admin.thread.list', [args], backgroundCall(background))
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@greendrake/vue-api",
-    "version": "0.2.0",
+    "version": "0.4.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.4.0",
+        "@greendrake/ui": "0.4.0",
+        "@greendrake/util": "0.4.0",
+        "@greendrake/vue-kit": "0.4.0"
     },
     "peerDependencies": {
         "pinia": "^3.0.4",
         "vue": "^3.5.34"
     },
     "devDependencies": {
-        "@greendrake/dev-config": "0.2.0",
+        "@greendrake/dev-config": "0.4.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 an app's boot, for a bootstrap that offers
+// these two hooks. 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.onRouter wires it to the app's router.
     goHome?: () => void
     // Read once, when useConnectivity is first instantiated.
     connectionSource?: ConnectionSource