@eleven-am/golem-react 0.1.1 → 0.2.1

package/README.md

@@ -10,13 +10,13 @@ Built on `@eleven-am/golem-client` and `@tanstack/react-query`.
 npm install @eleven-am/golem-react @eleven-am/golem-client @tanstack/react-query react gql.tada graphql graphql-ws
 ```
 
-Peer dependencies: `@eleven-am/golem-client` ^0.1.0, `@tanstack/react-query` ^5, `react` >=18, `gql.tada` ^1.8. The client in turn needs `graphql` ^16 and `graphql-ws` ^6 (and `@tanstack/query-core` ^5, which `@tanstack/react-query` brings).
+Peer dependencies: `@eleven-am/golem-client` ^0.2.1, `@tanstack/react-query` ^5, `react` >=18, `gql.tada` ^1.8. The client in turn needs `graphql` ^16 and `graphql-ws` ^6 (and `@tanstack/query-core` ^5, which `@tanstack/react-query` brings).
 
 ## Setup
 
 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
 
@@ -84,6 +84,10 @@ const status = useGolemStatus(POSTS)
 return <small>{status?.state}</small>
 ```
 
+### useGolemConnection
+
+The connection state of the whole client, as one of the `transport.status` values: `idle` before any live query has opened a connection, then `connecting`, `open`, `reconnecting` or one of the fatal states. It is global, unlike `useGolemStatus`.
+
 ### useGolemMutation
 
 `useMutation` over `client.mutate`. A committed mutation invalidates every cached query over the models it touches, so the live event or the refetch brings it up to date. The mutation result is never written into the cache. A document holds exactly one operation.
@@ -117,7 +121,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 +131,7 @@ const COUNT = `
 `
 
 const total = useGolemStaticQuery(COUNT)
+const liveTotal = useGolemQuery(COUNT)
 ```
 
 ## Live status
@@ -194,17 +199,11 @@ The client adds `_version` and `__typename` to every selection of a model with e
 - `golem.transport.status`: `idle`, `connecting`, `open`, `reconnecting`, `unauthenticated`, `forbidden`, `invalid`, `protocol-mismatch`, `contract-mismatch` or `deadline-required`.
 - `golem.transport.onStatus(listener)`: calls you on every change and returns an unsubscribe function.
 
-Wrap them in `useSyncExternalStore`:
+`useGolemConnection()` wraps both and returns the transport status. It re-renders on every change.
 
 ```tsx
-import { useSyncExternalStore } from 'react'
-
-function useConnection() {
-  return useSyncExternalStore(
-    (notify) => golem.transport.onStatus(notify),
-    () => golem.transport.status,
-  )
-}
+const connection = useGolemConnection()
+return connection === 'open' ? null : <small>{connection}</small>
 ```
 
 #### Why there is a manifest
@@ -221,6 +220,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 +245,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/dist/status.d.ts

@@ -1,8 +1,9 @@
 import { type QueryKey } from '@tanstack/react-query';
-import type { GolemClient, LiveStatus } from '@eleven-am/golem-client';
+import type { GolemClient, LiveStatus, SessionStatus } from '@eleven-am/golem-client';
 import type { GolemDocument } from './types.js';
 export declare function useLiveStatus(client: GolemClient, queryKey: QueryKey): LiveStatus | undefined;
 export interface GolemStatusOptions {
     readonly infinite?: boolean;
 }
 export declare function useGolemStatus(document: GolemDocument, variables?: Readonly<Record<string, unknown>>, options?: GolemStatusOptions): LiveStatus | undefined;
+export declare function useGolemConnection(): SessionStatus;

package/dist/status.js

@@ -16,3 +16,9 @@ export function useGolemStatus(document, variables = {}, options = {}) {
     const queryKey = useMemo(() => (options.infinite === true ? client.infiniteQueryOptions(document, variables) : client.queryOptions(document, variables)).queryKey, [client, document, variablesHash, options.infinite]);
     return useLiveStatus(client, queryKey);
 }
+export function useGolemConnection() {
+    const client = useGolemClient();
+    const subscribe = useCallback((listener) => client.transport.onStatus(listener), [client]);
+    const snapshot = useCallback(() => client.transport.status, [client]);
+    return useSyncExternalStore(subscribe, snapshot, snapshot);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eleven-am/golem-react",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "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.1",
     "@tanstack/react-query": "^5.0.0",
     "gql.tada": "^1.8.0",
     "react": ">=18"