@eleven-am/golem-client 0.1.1 → 0.2.1

package/README.md

@@ -34,7 +34,7 @@ export const golem = new GolemClient({
 |---|---|
 | `queryClient` | Required. Your application's TanStack `QueryClient`. A second `GolemClient` on a `QueryClient` that already has one throws `GolemConfigurationError`. |
 | `url` | The GraphQL endpoint. HTTP requests go to it; the WebSocket connects to the same URL. |
-| `manifest` | The generated `zz_golem_client.gen.ts` of your golem server (go/v0.8.2 or later). |
+| `manifest` | The generated `zz_golem_client.gen.ts` of your golem server (go/v0.8.3 or later). |
 | `credentials` | Optional function returning `{ headers, connectionParams }`. Called again for every request and every connection, including after the server closes a socket at its credential deadline, so return the current token each time. |
 | `createSocket` | Optional `(url, protocols, credentials) => socket` factory, for a WebSocket implementation of your own (for example in Node). |
 | `fetch` | Optional `fetch` implementation for HTTP requests. Defaults to `globalThis.fetch`. |
@@ -58,7 +58,7 @@ const unsubscribe = observer.subscribe((result) => render(result.data))
 - `golem.live.start()` starts live sync and returns a function that stops it. Start it before you observe a query, so no query is fetched before its subscriptions are open.
 - `golem.queryOptions(document, variables?)` returns TanStack options for a live query. It throws `GolemNotLiveError` for a document that cannot be live.
 - `golem.infiniteQueryOptions(document, variables?)` returns options for `InfiniteQueryObserver` over a list query with a `take`. Give `take` a variable with a default, or a literal; never write `cursor` or `skip`.
-- `golem.staticQueryOptions(document, variables?)` returns options for a document that cannot be live (aggregates, group-by, counts, update-many roots). It is fetched once and never patched.
+- `golem.staticQueryOptions(document, variables?)` returns options for a document fetched once and never refreshed, including one that cannot be live (a model without events, a custom root with no model rows). Counts, aggregates, group-by and custom roots with model rows are live through `golem.queryOptions`: any event on a model they come from refetches the document through the coalescer, and they are never patched.
 - `golem.mutate(document, variables?)` runs a mutation over HTTP and returns its data. A document holds exactly one operation; one with several is refused with `GolemMultipleOperationsError`.
 
 ```ts
@@ -151,18 +151,7 @@ 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 your framework's external-store primitive. In React that is `useSyncExternalStore`:
-
-```tsx
-import { useSyncExternalStore } from 'react'
-
-function useConnection() {
-  return useSyncExternalStore(
-    (notify) => golem.transport.onStatus(notify),
-    () => golem.transport.status,
-  )
-}
-```
+Wrap them in your framework's external-store primitive. In React, `useGolemConnection()` from `@eleven-am/golem-react` does it.
 
 #### Why there is a manifest
 
@@ -178,6 +167,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. To send a last mutation on `pagehide`, pass `keepalive`; only that request is sent with `fetch(..., { keepalive: true })`.
+
+```ts
+addEventListener('pagehide', () => {
+  void golem.mutate(END_SESSION, { id: sessionId }, { keepalive: true }).catch(() => {})
+})
+```
+
+The third argument is either an `AbortSignal` or `{ signal?, keepalive? }`. 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:
@@ -191,7 +192,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.
 - `@tanstack/query-core` 5.
 - A socket deadline for every principal. See [The socket deadline](https://github.com/eleven-am/golem/blob/main/docs/golem-go/GUIDE.md#the-socket-deadline).
 

package/dist/analysis.d.ts

@@ -7,6 +7,7 @@ export interface StreamPlan {
     readonly model: string;
     readonly eventsRoot: string;
     readonly patchable: boolean;
+    readonly derived: boolean;
     readonly scope: 'exact' | 'policy-only';
     readonly paths: ReadonlyArray<string>;
     readonly query: string;

package/dist/analysis.js

@@ -164,7 +164,7 @@ function visitField(field, models, scope, path, state, walk) {
             return field;
         }
         state.nested = true;
-        return { ...field, selectionSet: rows(field.selectionSet, computed, null, false, childPath(path, field), walk) };
+        return { ...field, selectionSet: rows(field.selectionSet, computed, null, false, false, childPath(path, field), walk) };
     }
     fields.set(responseKey(field), field);
     return field;
@@ -187,9 +187,9 @@ function visitRelation(field, owner, relation, scope, path, walk) {
         inverseFilter = objectValue({ [relation.inverse]: objectValue({ [inverse.list ? 'some' : 'is']: scope }) });
     }
     const childScope = conjunction(filterScope(argument(field, 'where')?.value), inverseFilter);
-    return { ...field, selectionSet: rows(field.selectionSet, [relation.target], childScope, false, childPath(path, field), walk) };
+    return { ...field, selectionSet: rows(field.selectionSet, [relation.target], childScope, false, false, childPath(path, field), walk) };
 }
-function rows(set, models, scope, plain, path, walk) {
+function rows(set, models, scope, plain, derived, path, walk) {
     const order = walk.sink === null ? 0 : walk.sink.sequence++;
     const state = { fields: new Map(models.map((model) => [model, new Map()])), nested: false };
     let selections = visitSet(set, models, scope, path, state, walk);
@@ -200,7 +200,7 @@ function rows(set, models, scope, plain, path, walk) {
     else {
         selections = ensure(selections, [TYPENAME_FIELD]);
     }
-    register(models, scope, plain && !state.nested, order, path, state, walk);
+    register(models, scope, plain && !state.nested, derived, order, path, state, walk);
     return { ...set, selections };
 }
 function disagrees(draft, fields) {
@@ -212,7 +212,7 @@ function disagrees(draft, fields) {
     }
     return false;
 }
-function register(models, scope, patchable, order, path, state, walk) {
+function register(models, scope, patchable, derived, order, path, state, walk) {
     const sink = walk.sink;
     if (sink === null) {
         return;
@@ -235,11 +235,12 @@ function register(models, scope, patchable, order, path, state, walk) {
             draft = sink.streams.get(key);
         }
         if (draft === undefined) {
-            draft = { key, model: name, eventsRoot: model.events, patchable, scope, order, fields: new Map(), paths: new Set() };
+            draft = { key, model: name, eventsRoot: model.events, patchable, derived, scope, order, fields: new Map(), paths: new Set() };
             sink.streams.set(key, draft);
         }
         else {
             draft.patchable &&= patchable;
+            draft.derived ||= derived;
         }
         draft.paths.add(path);
         for (const [responseName, field] of fields) {
@@ -294,6 +295,7 @@ function finish(draft, manifest, operation) {
         model: draft.model,
         eventsRoot: draft.eventsRoot,
         patchable: draft.patchable,
+        derived: draft.derived,
         scope: draft.scope === null ? 'policy-only' : 'exact',
         paths: [...draft.paths].sort(),
         query: print(document),
@@ -337,6 +339,9 @@ function visitRoot(field, walk) {
         if (modelName === undefined || model === undefined) {
             throw new GolemDocumentError(`the manifest root ${name} names no model`);
         }
+        if (root.shape === 'aggregate' || root.shape === 'groupBy') {
+            return derivedRoot(field, root, walk);
+        }
         if (root.shape !== 'rows' && root.shape !== 'row' && root.shape !== 'deletedRow') {
             record(walk.sink, new GolemNotLiveError('non-row-root', name, `${name} is not live: its result shape is ${root.shape}, not model rows`), `non-row-root|${name}`);
             return field;
@@ -348,14 +353,23 @@ function visitRoot(field, walk) {
         const scope = root.shape === 'rows' ? filterScope(where) : uniqueScope(model, where);
         markNullable(field, root, walk);
         const plain = (field.arguments ?? []).every((candidate) => candidate.name.value === 'where');
-        return { ...field, selectionSet: rows(field.selectionSet, [modelName], scope, plain, responseKey(field), walk) };
+        return { ...field, selectionSet: rows(field.selectionSet, [modelName], scope, plain, false, responseKey(field), walk) };
     }
     if (root.models.length === 0 || field.selectionSet === undefined) {
         record(walk.sink, new GolemNotLiveError('opaque-root-without-models', name, `${name} is not live: the custom root's result holds no model rows`), `opaque-root-without-models|${name}`);
         return field;
     }
     markNullable(field, root, walk);
-    return { ...field, selectionSet: rows(field.selectionSet, root.models, null, false, responseKey(field), walk) };
+    return { ...field, selectionSet: rows(field.selectionSet, root.models, null, false, true, responseKey(field), walk) };
+}
+function derivedRoot(field, root, walk) {
+    const order = walk.sink === null ? 0 : walk.sink.sequence++;
+    const scope = filterScope(argument(field, 'where')?.value);
+    root.models.forEach((model, index) => {
+        const state = { fields: new Map([[model, new Map()]]), nested: false };
+        register([model], index === 0 ? scope : null, false, true, order, responseKey(field), state, walk);
+    });
+    return field;
 }
 function markNullable(field, root, walk) {
     if ((root.shape === 'row' || root.shape === 'deletedRow') && root.nullable && walk.sink !== null) {
@@ -370,7 +384,7 @@ function rewriteFragment(definition, walk) {
     if (walk.manifest.models[condition] === undefined) {
         return definition;
     }
-    return { ...definition, selectionSet: rows(definition.selectionSet, [condition], null, false, '', walk) };
+    return { ...definition, selectionSet: rows(definition.selectionSet, [condition], null, false, false, '', walk) };
 }
 export function operationOf(document, kind) {
     const operations = document.definitions.filter((definition) => definition.kind === Kind.OPERATION_DEFINITION);

package/dist/client.d.ts

@@ -3,7 +3,7 @@ import type { QueryClient, QueryFunctionContext } from '@tanstack/query-core';
 import { DocumentAnalyzer } from './analysis.js';
 import { LiveSync } from './live.js';
 import type { ClientManifest } from './manifest.js';
-import { Mutations } from './mutations.js';
+import { Mutations, type MutateOptions } from './mutations.js';
 import type { CredentialsGetter, SocketFactory } from './session.js';
 import { Transport } from './transport.js';
 export interface GolemClientOptions {
@@ -43,7 +43,7 @@ export declare class GolemClient {
         queryKey: readonly ["golem", "static", string, Readonly<Record<string, unknown>>];
         queryFn: (context: Pick<QueryFunctionContext, "signal">) => Promise<unknown>;
     };
-    mutate<T = unknown>(document: DocumentNode | string, variables?: Readonly<Record<string, unknown>>, signal?: AbortSignal): Promise<T>;
+    mutate<T = unknown>(document: DocumentNode | string, variables?: Readonly<Record<string, unknown>>, options?: AbortSignal | MutateOptions): Promise<T>;
     attach(): () => void;
     dispose(): void;
 }

package/dist/client.js

@@ -45,8 +45,8 @@ export class GolemClient {
             queryFn: (context) => this.transport.execute({ query: analysis.query, variables, signal: context.signal }),
         };
     }
-    mutate(document, variables, signal) {
-        return this.mutations.execute(document, variables, signal);
+    mutate(document, variables, options) {
+        return this.mutations.execute(document, variables, options);
     }
     attach() {
         this.holds++;

package/dist/errors.d.ts

@@ -51,6 +51,12 @@ export declare class GolemProtocolError extends Error {
 export declare class GolemConfigurationError extends Error {
     constructor(message: string);
 }
+export declare const KEEPALIVE_BODY_LIMIT = 65536;
+export declare class GolemKeepaliveTooLargeError extends Error {
+    readonly bytes: number;
+    readonly limit: number;
+    constructor(bytes: number);
+}
 export type NotLiveReason = 'model-without-events' | 'opaque-root-without-models' | 'hidden-inverse' | 'non-row-root';
 export declare class GolemNotLiveError extends Error {
     readonly reason: NotLiveReason;

package/dist/errors.js

@@ -69,6 +69,17 @@ export class GolemConfigurationError extends Error {
         this.name = 'GolemConfigurationError';
     }
 }
+export const KEEPALIVE_BODY_LIMIT = 65536;
+export class GolemKeepaliveTooLargeError extends Error {
+    bytes;
+    limit;
+    constructor(bytes) {
+        super(`a keepalive request body is ${bytes} bytes; browsers allow at most ${KEEPALIVE_BODY_LIMIT}`);
+        this.name = 'GolemKeepaliveTooLargeError';
+        this.bytes = bytes;
+        this.limit = KEEPALIVE_BODY_LIMIT;
+    }
+}
 export class GolemNotLiveError extends Error {
     reason;
     subject;

package/dist/live.d.ts

@@ -77,6 +77,7 @@ export declare class LiveSync {
         };
     };
     statusOf(query: Query): LiveStatus | undefined;
+    private hasQueuedRefetch;
     subscribeStatus(listener: () => void): () => void;
     private onCacheEvent;
     private reconcileHold;

package/dist/live.js

@@ -105,6 +105,10 @@ export class LiveSync {
     statusOf(query) {
         return this.statuses.get(query.queryHash);
     }
+    hasQueuedRefetch(query) {
+        const entry = this.entries.get(query.queryHash);
+        return entry !== undefined && (entry.coalescer.pending || entry.derivedStale);
+    }
     subscribeStatus(listener) {
         this.listeners.add(listener);
         return () => {
@@ -157,6 +161,7 @@ export class LiveSync {
             waiters: new Set(),
             merge: EMPTY_MERGE_STATE,
             inFlight: 0,
+            derivedStale: false,
             outage: query.state.dataUpdatedAt !== 0,
             bypass: false,
             everLive: false,
@@ -410,6 +415,11 @@ export class LiveSync {
         }
     }
     onEvent(entry, stream, frame) {
+        if (stream.plan.derived) {
+            entry.derivedStale = entry.inFlight > 0;
+            entry.coalescer.request();
+            return;
+        }
         const key = this.patcher.eventKey(stream.plan.model, frame.id, frame.entity);
         const version = parseVersion(frame.version);
         const receivedAt = this.clock();
@@ -516,6 +526,7 @@ export class LiveSync {
         const issuedAt = this.clock();
         if (live !== undefined) {
             live.inFlight++;
+            live.derivedStale = false;
         }
         try {
             const data = await this.transport.execute({ ...request, signal: context.signal });
@@ -535,6 +546,10 @@ export class LiveSync {
                 live.inFlight--;
                 if (live.inFlight === 0) {
                     live.merge = EMPTY_MERGE_STATE;
+                    if (live.derivedStale) {
+                        live.derivedStale = false;
+                        live.coalescer.request();
+                    }
                 }
             }
         }

package/dist/mutations.d.ts

@@ -2,6 +2,10 @@ import type { DocumentNode } from 'graphql';
 import type { QueryClient } from '@tanstack/query-core';
 import type { ClientManifest } from './manifest.js';
 import type { ExecuteRequest } from './transport.js';
+export interface MutateOptions {
+    readonly signal?: AbortSignal;
+    readonly keepalive?: boolean;
+}
 export interface MutationTransport {
     execute<T = unknown>(request: ExecuteRequest): Promise<T>;
 }
@@ -15,6 +19,6 @@ export declare class Mutations {
     private readonly transport;
     private readonly manifest;
     constructor(options: MutationsOptions);
-    execute<T = unknown>(document: DocumentNode | string, variables?: Readonly<Record<string, unknown>>, signal?: AbortSignal): Promise<T>;
+    execute<T = unknown>(document: DocumentNode | string, variables?: Readonly<Record<string, unknown>>, options?: AbortSignal | MutateOptions): Promise<T>;
     private invalidateCommitted;
 }

package/dist/mutations.js

@@ -1,6 +1,9 @@
 import { analyzeMutation } from './analysis.js';
 import { GolemCommitUnknownError, GolemPartialCommitError } from './errors.js';
 import { readMeta } from './live.js';
+function isAbortSignal(value) {
+    return value !== undefined && typeof value.aborted === 'boolean' && typeof value.addEventListener === 'function';
+}
 export class Mutations {
     client;
     transport;
@@ -10,11 +13,12 @@ export class Mutations {
         this.transport = options.transport;
         this.manifest = options.manifest;
     }
-    async execute(document, variables, signal) {
+    async execute(document, variables, options) {
+        const { signal, keepalive } = isAbortSignal(options) ? { signal: options, keepalive: undefined } : (options ?? {});
         const analysis = analyzeMutation(document, this.manifest);
         let data;
         try {
-            data = await this.transport.execute({ query: analysis.query, variables, signal });
+            data = await this.transport.execute({ query: analysis.query, variables, signal, keepalive });
         }
         catch (error) {
             if (error instanceof GolemPartialCommitError || error instanceof GolemCommitUnknownError) {

package/dist/transport.d.ts

@@ -13,6 +13,7 @@ export interface ExecuteRequest {
     readonly query: string;
     readonly variables?: Readonly<Record<string, unknown>>;
     readonly signal?: AbortSignal;
+    readonly keepalive?: boolean;
 }
 export declare class Transport {
     private readonly options;

package/dist/transport.js

@@ -1,4 +1,4 @@
-import { GolemConfigurationError, GolemHttpError, GolemProtocolError, failureOf } from './errors.js';
+import { GolemConfigurationError, GolemHttpError, GolemKeepaliveTooLargeError, KEEPALIVE_BODY_LIMIT, GolemProtocolError, failureOf } from './errors.js';
 import { golemBlock } from './protocol.js';
 import { Session } from './session.js';
 export class Transport {
@@ -29,15 +29,23 @@ export class Transport {
     async execute(request) {
         const credentials = (await this.options.credentials?.()) ?? {};
         const send = this.options.fetch ?? globalThis.fetch;
+        const payload = JSON.stringify({
+            query: request.query,
+            variables: request.variables,
+            extensions: { golem: golemBlock(this.options.manifest) },
+        });
+        if (request.keepalive === true) {
+            const bytes = new TextEncoder().encode(payload).length;
+            if (bytes > KEEPALIVE_BODY_LIMIT) {
+                throw new GolemKeepaliveTooLargeError(bytes);
+            }
+        }
         const response = await send(this.options.url, {
             method: 'POST',
             headers: { 'content-type': 'application/json', accept: 'application/json', ...credentials.headers },
-            body: JSON.stringify({
-                query: request.query,
-                variables: request.variables,
-                extensions: { golem: golemBlock(this.options.manifest) },
-            }),
+            body: payload,
             signal: request.signal,
+            ...(request.keepalive === true ? { keepalive: true } : {}),
         });
         const text = await response.text();
         let body;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eleven-am/golem-client",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Live GraphQL client for golem backends",
   "type": "module",
   "main": "dist/index.js",