foldkit-remote 0.10.0 → 0.12.0

package/README.md

@@ -331,13 +331,62 @@ const clientLayer = RemoteServer.memory({
 }).layer
 ```
 
-With a server, adapt your configured Effect RPC client instead; the
+With a server, hand Remote the Effect RPC client for `RemoteRpc`; the
 [server guide](../remote-server/README.md) supplies the other side:
 
 ```ts
-const clientLayer = Remote.clientLayer(rpcClient)
+import { Effect, Layer } from 'effect'
+import { FetchHttpClient } from 'effect/http'
+import { RpcClient, RpcSerialization } from 'effect/rpc'
+import { RemoteRpc } from 'foldkit-remote'
+
+const clientLayer = Layer.unwrap(
+  Effect.map(RpcClient.make(RemoteRpc), rpcClient => Remote.clientLayer(rpcClient)),
+).pipe(
+  Layer.provide(RpcClient.layerProtocolHttp({ url: '/rpc' })),
+  Layer.provide([RpcSerialization.layerJson, FetchHttpClient.layer]),
+)
+```
+
+Or, with no Effect RPC on the server, plain JSON over HTTP: each call a `POST`
+of `{ operation, payload }`, answered `{ result }` or `{ error }`.
+[`RemoteServer.answer`](../remote-server/README.md#over-plain-json) is the
+other end. `Remote.json(send)` is the same client over any other way of
+sending the request, a worker or a server running in the page:
+
+```ts
+const overHttp = Remote.clientLayer(
+  Remote.http('/remote', { headers: () => ({ 'x-session': 'the session token' }) }),
+)
 ```
 
+`headers` is read for each request, so a token that changes reaches the next
+call. Neither carries live data.
+
+For a server in a worker or in the page (a sandbox), `foldkit-remote/port`
+speaks Effect's own RPC worker protocol over a `MessagePort`, so live data,
+typed errors and interruption cross it too.
+[`servePort`](../remote-server/README.md#over-a-messageport) is the other end:
+
+```ts
+import { port } from 'foldkit-remote/port'
+
+// A new conversation each time the protocol connects: one port here, the other to the server.
+const overPort = port(() => {
+  const channel = new MessageChannel()
+  worker.port.postMessage({ open: 'remote' }, [channel.port2])
+  return channel.port1
+})
+```
+
+It is a `Layer<RemoteClient>` like the others; a port that cannot be set up is
+a defect, not a failed read.
+
+The stock client is accepted as it is. When its transport fails, the call
+fails with its own Remote error (`RemoteReadError`, `RemoteQueryError`,
+`RemoteMutationError`, `RemoteLiveError`), which the UI shows and retries like
+any other failure.
+
 Either is a Layer the runtime provides to `subscriptions` and Commands. The
 transport itself is not owned by Remote. See
 [`RemoteServer.memory`](../remote-server/README.md#a-backend-held-in-memory)
@@ -1755,7 +1804,9 @@ The wire schemas (`ReadBatch`, `QueryRequest`, `MutationRequest`,
 `LiveRequirement`, results/errors) and the `RemoteRpc` group are exported.
 
 `Remote.clientLayer(rpcClient, { window? })` adapts an Effect RPC client,
-including live-change mapping. Compatible reads and queries coalesce:
+including live-change mapping. It takes the client `RpcClient.make(RemoteRpc)`
+builds, whose calls can also fail with `RpcClientError`; each such failure
+becomes the call's Remote error rather than a defect. Compatible reads and queries coalesce:
 requirements issued together become one `ReadBatch`, an identical in-flight
 requirement/query is joined, and a failed request releases the coalesced entry.
 A relation request with its own pagination window stays separate because one