@greendrake/rpc 0.6.0 → 0.8.0

package/README.md

@@ -54,7 +54,7 @@ const user = await client.call('user.get', 'U1') // User
 await client.call('user.update', { id: 'U1', name: 'Ann' })
 ```
 
-`new RpcClient<M>(transport, locale?)` — `locale` is `() => string | undefined`, evaluated per call, so a language switch applies from the next call. `call(method, ...args)` is the one way to invoke a method, and every request it sends carries a nonce. `MethodMap` and `MethodMapConstraint<M>` are the constraint types; a plain interface qualifies.
+`new RpcClient<M>(transport, locale?)` — `locale` is `() => string | undefined`, evaluated per call, so a language switch applies from the next call. `call(method, ...args)` is the one way to invoke a method, and every request it sends carries a nonce. A method that takes no arguments is called with none, and its request carries no `arguments` field. `Caller<M>` is that `call`, which `RpcClient` and `@greendrake/vue-api`'s `ApiClient` both implement: the type for code handed either. `MethodMap` and `MethodMapConstraint<M>` are the constraint types; a plain interface qualifies.
 
 `Transport` is one method, `send(request: RpcRequest): Promise<unknown>`, resolving to the response `data` or rejecting with a mapped error. Anything implementing it plugs into the client.
 
@@ -177,7 +177,7 @@ The contract:
 - **Relevance.** `when` decides whether a push concerns what the binding shows; omitted, every push does.
 - **Apply or resync.** `apply` folds the push in and nothing else happens. Without it the push runs `resync` — so `{}` means "every such push re-reads". A handler with neither `apply` nor a `resync` to fall back on throws at binding time.
 - **Reconnect.** `resync` also runs when the socket returns from a drop the binding witnessed: a connection has no memory, so what it missed is only recoverable by asking. The first connect after the binding is created is not a return from a drop. A binding without `resync` subscribes to nothing connection-related.
-- **Coalescing.** One `resync` at a time; pushes arriving during a run collapse into a single follow-up after it, however many there are — they ask the same question.
+- **Coalescing.** One `resync` at a time; pushes arriving during a run collapse into a single follow-up after it, however many there are — they ask the same question. This is `@greendrake/util`'s `coalesced`, which a server building what it pushes can use the same way.
 - **No error policy.** The binding awaits `resync` only to know when the slot is free, and interprets neither outcome: `resync` owns its errors. It must also not be served by a response cache the missed pushes would have invalidated — invalidate the entries its read would hit, then read.
 - **Release.** The returned function detaches every subscription and drops any pending follow-up; calling it twice is harmless.
 
@@ -211,7 +211,6 @@ cache.get('taxonomy.tree', [{ taxonomy: 'category' }]) // { hit: boolean; data?:
 cache.set('taxonomy.tree', [{ taxonomy: 'category' }], tree) // no-op for an unlisted method
 cache.invalidate('search.things') // every entry for the method
 cache.invalidate('search.things', { q: 'x' }) // that args-key only
-cache.prime('taxonomy.tree', [{ taxonomy: 'category' }], pushed) // seed from a server push
 cache.clear() // everything, e.g. when the session identity changes
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@greendrake/rpc",
-    "version": "0.6.0",
+    "version": "0.8.0",
     "description": "RPC client over JSON: typed method-map API, HTTP and reconnecting WebSocket transports, pluggable codec and headers, TTL response cache",
     "license": "MIT",
     "author": "Eugene Greendrake <eugene@greendrake.nz>",
@@ -34,10 +34,10 @@
     },
     "prettier": "@greendrake/dev-config/prettier",
     "dependencies": {
-        "@greendrake/util": "0.6.0"
+        "@greendrake/util": "^0.8.0"
     },
     "devDependencies": {
-        "@greendrake/dev-config": "0.6.0",
+        "@greendrake/dev-config": "0.7.0",
         "typescript": "6.0.3"
     }
 }

package/src/ResponseCache.ts

@@ -85,12 +85,4 @@ export class ResponseCache {
     clear(): void {
         this.#entries.clear()
     }
-
-    // Seed the cache with a known-fresh response — a server push already
-    // carrying the full DTO a read would return — so the next read serves it
-    // without a round-trip. `args` must match the read's args so the same key
-    // is hit.
-    prime(method: string, args: unknown[], data: unknown): void {
-        this.set(method, args, data)
-    }
 }

package/src/RpcClient.ts

@@ -1,4 +1,4 @@
-import type { MethodMap, MethodMapConstraint, Transport } from './types'
+import type { Caller, MethodMap, MethodMapConstraint, Transport } from './types'
 import { packRequest } from './protocol'
 
 // Typed facade over a transport: methods come from the app's declared
@@ -6,7 +6,7 @@ import { packRequest } from './protocol'
 // proxies, no casts at call sites.
 //    const client = new RpcClient<Methods>(transport)
 //    const user = await client.call('user.get', id)
-export class RpcClient<M extends MethodMapConstraint<M> = MethodMap> {
+export class RpcClient<M extends MethodMapConstraint<M> = MethodMap> implements Caller<M> {
     readonly transport: Transport
     // Supplies the caller's UI language tag per request. Evaluated per call,
     // like HttpTransport's headers provider, so a locale switch takes effect on

package/src/liveBinding.ts

@@ -1,3 +1,4 @@
+import { coalesced } from '@greendrake/util'
 import type { PushMapConstraint, WsTransport } from './WsTransport'
 
 // What one push means to the thing the binding keeps current.
@@ -36,38 +37,17 @@ export interface LiveOptions<PEvents, PData> {
 export const liveBinding = <PEvents extends PushMapConstraint<PEvents>, PData extends PushMapConstraint<PData>>(transport: WsTransport<PEvents, PData>, options: LiveOptions<PEvents, PData>): (() => void) => {
     const { resync } = options
     const releases: (() => void)[] = []
-    let running = false
-    let queued = false
     let released = false
 
+    // One re-read at a time, and at most one more behind it however many
+    // pushes land while it runs: they all ask the same question, and the answer
+    // to the last one is the answer to all of them. One still queued when the
+    // binding is released has nobody left to answer, and does nothing.
+    const reread = coalesced(() => (released ? undefined : resync?.()))
+    // The outcome belongs to resync — swallowed here rather than left
+    // unhandled because this runs from a subscription callback nobody awaits.
     const runResync = (): void => {
-        if (!resync || released) return
-        // One re-read at a time, and at most one more behind it however many
-        // pushes land while it runs: they all ask the same question, and the
-        // answer to the last one is the answer to all of them.
-        if (running) {
-            queued = true
-            return
-        }
-        running = true
-        // `new Promise(resolve => resolve(…))` rather than Promise.resolve(…):
-        // it puts the call inside the promise, so a resync that throws
-        // synchronously becomes a rejection like any other failure instead of
-        // escaping with the slot still held — which would wedge this binding for
-        // good, and abort the transport's dispatch to every other subscriber of
-        // the same frame.
-        void new Promise(resolve => resolve(resync()))
-            // Whatever the outcome, the slot is free and a push that arrived
-            // during the run gets its re-read. The outcome itself belongs to
-            // resync — swallowed here rather than left unhandled because this
-            // runs from a subscription callback nobody awaits.
-            .catch(() => {})
-            .then(() => {
-                running = false
-                if (!queued) return
-                queued = false
-                runResync()
-            })
+        void reread().catch(() => {})
     }
 
     const attach = <P>(handlers: { [K in keyof P]?: LiveHandler<P[K]> } | undefined, subscribe: <K extends keyof P & string>(key: K, handler: (data: P[K]) => void) => () => void): (() => () => void)[] =>
@@ -109,7 +89,6 @@ export const liveBinding = <PEvents extends PushMapConstraint<PEvents>, PData ex
 
     return () => {
         released = true
-        queued = false
         releases.forEach(release => release())
         releases.length = 0
     }

package/src/main.ts

@@ -1,4 +1,4 @@
-export { identityCodec, type Codec, type HeadersProvider, type RpcRequest, type RpcResponse, type MethodMap, type MethodMapConstraint, type Transport } from './types'
+export { identityCodec, type Caller, type Codec, type HeadersProvider, type RpcRequest, type RpcResponse, type MethodMap, type MethodMapConstraint, type Transport } from './types'
 export { ApiError, NotFoundError, OneOutcomeError, WebSocketClosedError, codeOf } from './errors'
 export { makeError, packRequest, settleResponse } from './protocol'
 export { HttpTransport, type HttpTransportOptions } from './http'

package/src/types.ts

@@ -51,6 +51,12 @@ export type MethodMap = Record<string, (...args: never[]) => unknown>
 
 export type MethodMapConstraint<M> = Record<keyof M, (...args: never[]) => unknown>
 
+// What calls the methods of M: each with exactly its own arguments, and a method
+// that takes none with none at all.
+export interface Caller<M extends MethodMapConstraint<M>> {
+    call<K extends keyof M & string>(method: K, ...args: Parameters<M[K]>): Promise<Awaited<ReturnType<M[K]>>>
+}
+
 export interface Transport {
     send(request: RpcRequest): Promise<unknown>
 }