@eleven-am/golem-react 0.1.1 → 0.2.0

package/README.md

@@ -16,7 +16,7 @@ Peer dependencies: `@eleven-am/golem-client` ^0.1.0, `@tanstack/react-query` ^5,
 
 The client lives on your application's `QueryClient`. It does not make a second one.
 
-The manifest is `zz_golem_client.gen.ts`, written by `golem generate` beside your GraphQL schema on the server (go/v0.8.2 or later). Copy or import it into your front end, and regenerate it whenever the schema changes. Never edit it.
+The manifest is `zz_golem_client.gen.ts`, written by `golem generate` beside your GraphQL schema on the server (go/v0.8.3 or later). Copy or import it into your front end, and regenerate it whenever the schema changes. Never edit it.
 
 ```tsx
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
@@ -73,7 +73,7 @@ function Posts() {
 }
 ```
 
-It throws `GolemNotLiveError` (naming the reason and the root) for a document that cannot be live. Use `useGolemStaticQuery` for those.
+Aggregates, group-by, relation group-by and custom roots that return model rows are live: any event on a model they come from refetches the document through the coalescer, and they are never patched. Put counts in their own query. It throws `GolemNotLiveError` (naming the reason and the root) for a document that reaches a model without events or a custom root whose result holds no model rows. Use `useGolemStaticQuery` for those. Relation group-by needs a go/v0.8.3 manifest to refetch on events of the models it groups by.
 
 ### useGolemStatus
 
@@ -117,7 +117,7 @@ const pages = feed.data?.pages ?? []
 
 ### useGolemStaticQuery
 
-`useQuery` for a document that cannot be live: aggregates, group-by, counts and update-many roots. Fetched once, never patched.
+`useQuery` for a document you want fetched once and never refreshed, or one that cannot be live (a model without events, a custom root with no model rows). Counts and aggregates are live through `useGolemQuery`.
 
 ```tsx
 const COUNT = `
@@ -127,6 +127,7 @@ const COUNT = `
 `
 
 const total = useGolemStaticQuery(COUNT)
+const liveTotal = useGolemQuery(COUNT)
 ```
 
 ## Live status
@@ -221,6 +222,18 @@ GraphQL does not say which subscription root carries a model's events, what its
 
 For a walkthrough from a model to a live component, see [Using golem from React](https://github.com/eleven-am/golem/blob/main/docs/golem-go/REACT.md).
 
+## Mutations on page unload
+
+Browsers cancel ordinary fetches while a page unloads. Pass `keepalive: true` to `useGolemMutation` and that mutation's requests are sent with `fetch(..., { keepalive: true })`.
+
+```tsx
+const endSession = useGolemMutation(END_SESSION, { keepalive: true })
+
+addEventListener('pagehide', () => endSession.mutate({ id: sessionId }))
+```
+
+The response may never be processed, so treat the mutation as possibly committed; the next page load refetches the authoritative state. Browsers cap keepalive request bodies at 64 KiB in total, so a larger body throws `GolemKeepaliveTooLargeError` before anything is sent.
+
 ## Errors
 
 All server errors are `GolemError` (`code`, `path`, `extensions`, `retryable`) or a subclass:
@@ -234,7 +247,7 @@ Client-side failures: `GolemConfigurationError` (bad setup), `GolemDocumentError
 
 ## Requirements
 
-- golem **go/v0.8.2 or later** on the server, with `golem.Subscriptions` on every model a live query reaches.
+- golem **go/v0.8.3 or later** on the server, with `golem.Subscriptions` on every model a live query reaches.
 - `react` >=18, `@tanstack/react-query` 5.
 - A socket deadline for every principal, and a manifest regenerated after every schema change. See [The socket deadline](https://github.com/eleven-am/golem/blob/main/docs/golem-go/GUIDE.md#the-socket-deadline) and [The client manifest](https://github.com/eleven-am/golem/blob/main/docs/golem-go/GUIDE.md#the-client-manifest).
 

package/dist/hooks.d.ts

@@ -3,7 +3,9 @@ import type { Cursor } from '@eleven-am/golem-client';
 import type { GolemDocument, ResultFor, VariablesFor } from './types.js';
 export type GolemQueryOptions<TData> = Omit<UseQueryOptions<TData, Error, TData, readonly unknown[]>, 'queryKey' | 'queryFn' | 'meta'>;
 export type GolemInfiniteQueryOptions<TPage> = Omit<UseInfiniteQueryOptions<TPage, Error, InfiniteData<TPage, Cursor | null>, readonly unknown[], Cursor | null>, 'queryKey' | 'queryFn' | 'meta' | 'initialPageParam' | 'getNextPageParam'>;
-export type GolemMutationOptions<TData, TVariables> = Omit<UseMutationOptions<TData, Error, TVariables>, 'mutationFn'>;
+export type GolemMutationOptions<TData, TVariables> = Omit<UseMutationOptions<TData, Error, TVariables>, 'mutationFn'> & {
+    readonly keepalive?: boolean;
+};
 export declare function useGolemQuery<TDocument extends GolemDocument>(document: TDocument, variables?: VariablesFor<TDocument>, options?: GolemQueryOptions<ResultFor<TDocument>>): UseQueryResult<ResultFor<TDocument>, Error>;
 export declare function useGolemStaticQuery<TDocument extends GolemDocument>(document: TDocument, variables?: VariablesFor<TDocument>, options?: GolemQueryOptions<ResultFor<TDocument>>): UseQueryResult<ResultFor<TDocument>, Error>;
 export declare function useGolemInfiniteQuery<TDocument extends GolemDocument>(document: TDocument, variables?: VariablesFor<TDocument>, options?: GolemInfiniteQueryOptions<ResultFor<TDocument>>): UseInfiniteQueryResult<InfiniteData<ResultFor<TDocument>, Cursor | null>, Error>;

package/dist/hooks.js

@@ -21,8 +21,9 @@ export function useGolemInfiniteQuery(document, variables, options) {
 }
 export function useGolemMutation(document, options) {
     const client = useGolemClient();
+    const { keepalive, ...mutation } = options ?? {};
     return useMutation({
-        ...options,
-        mutationFn: (variables) => client.mutate(document, variables),
+        ...mutation,
+        mutationFn: (variables) => client.mutate(document, variables, keepalive === undefined ? undefined : { keepalive }),
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eleven-am/golem-react",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "React bindings for the golem live GraphQL client",
   "type": "module",
   "main": "dist/index.js",
@@ -20,7 +20,7 @@
     "test": "tsc --noEmit -p tsconfig.spec.json && vitest run"
   },
   "peerDependencies": {
-    "@eleven-am/golem-client": "^0.1.1",
+    "@eleven-am/golem-client": "^0.2.0",
     "@tanstack/react-query": "^5.0.0",
     "gql.tada": "^1.8.0",
     "react": ">=18"