@lunora/client 1.0.0-alpha.2 → 1.0.0-alpha.200

package/LICENSE.md

@@ -103,3 +103,9 @@ Unless required by applicable law or agreed to in writing, software distributed
 under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
 CONDITIONS OF ANY KIND, either express or implied. See the License for the
 specific language governing permissions and limitations under the License.
+
+<!-- DEPENDENCIES -->
+<!-- /DEPENDENCIES -->
+
+<!-- TYPE_DEPENDENCIES -->
+<!-- /TYPE_DEPENDENCIES -->

package/README.md

@@ -34,7 +34,7 @@
 
 ---
 
-The framework-agnostic browser/edge SDK for Lunora. It runs RPC over HTTP and real-time deltas over a single multiplexed WebSocket, with optimistic updates, an offline mutation queue, and decorrelated-jitter reconnect built in. It is the lowest-level user-facing entry point that every framework adapter (React, Vue, Svelte, Solid) layers on top of.
+The framework-agnostic browser/edge SDK for Lunora. It runs RPC over HTTP and real-time deltas over a single multiplexed WebSocket, with optimistic updates, an offline mutation queue, and exponential-backoff-with-jitter reconnect built in. It is the lowest-level user-facing entry point that every framework adapter (React, Vue, Svelte, Solid) layers on top of.
 
 Part of the [Lunora](https://github.com/anolilab/lunora) framework — a type-safe, real-time backend on Cloudflare Workers + Durable Objects with a Vite-first DX.
 
@@ -63,8 +63,21 @@ const client = new LunoraClient({ url: "https://app.acme.test" });
 // One-shot query (HTTP, carries the D1 bookmark for read-your-writes).
 const messages = await client.query(api.messages.list, { room: "general" });
 
-// Mutation with an optimistic update applied to matching subscribers.
-await client.mutation(api.messages.send, { body: "hi" }, { optimistic: (current = []) => [...current, { body: "hi", pending: true }] });
+// Mutation with an optimistic update. `optimisticUpdate` names the query it
+// patches — a write and the queries it affects are different functions, and only
+// you know which. (The per-call `optimistic` shortcut patches the subscription
+// registered under the mutation's OWN reference and args, nothing else.)
+await client.mutation(
+    api.messages.send,
+    { room: "general", body: "hi" },
+    {
+        optimisticUpdate: (store, args) => {
+            const current = store.getQuery(api.messages.list, { room: args.room }) ?? [];
+
+            store.setQuery(api.messages.list, { room: args.room }, [...current, { body: args.body, pending: true }]);
+        },
+    },
+);
 
 // Live subscription over WS — returns an unsubscribe function.
 const unsubscribe = client.subscribe(api.messages.list, { room: "general" }, (next) => {
@@ -74,6 +87,8 @@ const unsubscribe = client.subscribe(api.messages.list, { room: "general" }, (ne
 client.close();
 ```
 
+`client.subscribeShape({ name, args }, cb)` is the [local-first sync engine](https://lunora.sh/docs/concepts/local-first)'s parallel to `subscribe`: it replicates a **partial view** of a table (a server-defined shape) over the poke diff protocol instead of re-running a query. Most apps consume it through [`@lunora/db`](https://www.npmjs.com/package/@lunora/db)'s `lunoraCollectionOptions({ shape })` rather than directly.
+
 > This README covers the basics. For the full API, options, and guides, see the **[documentation](https://lunora.sh/docs/api/client)**.
 
 ## Related