@eleven-am/golem-react 0.2.0 → 0.2.1

package/README.md

@@ -10,7 +10,7 @@ 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
 
@@ -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.
@@ -195,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

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.2.0",
+  "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.2.0",
+    "@eleven-am/golem-client": "^0.2.1",
     "@tanstack/react-query": "^5.0.0",
     "gql.tada": "^1.8.0",
     "react": ">=18"