@plasius/graph-client-react 0.1.1 → 0.1.2

package/README.md

@@ -1,22 +1,128 @@
 # @plasius/graph-client-react
 
-React bindings for @plasius/graph-client-core.
+[![npm version](https://img.shields.io/npm/v/@plasius/graph-client-react.svg)](https://www.npmjs.com/package/@plasius/graph-client-react)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/Plasius-LTD/graph-client-react/ci.yml?branch=main&label=build&style=flat)](https://github.com/Plasius-LTD/graph-client-react/actions/workflows/ci.yml)
+[![coverage](https://img.shields.io/codecov/c/github/Plasius-LTD/graph-client-react)](https://codecov.io/gh/Plasius-LTD/graph-client-react)
+[![License](https://img.shields.io/github/license/Plasius-LTD/graph-client-react)](./LICENSE)
+[![Code of Conduct](https://img.shields.io/badge/code%20of%20conduct-yes-blue.svg)](./CODE_OF_CONDUCT.md)
+[![Security Policy](https://img.shields.io/badge/security%20policy-yes-orange.svg)](./SECURITY.md)
+[![Changelog](https://img.shields.io/badge/changelog-md-blue.svg)](./CHANGELOG.md)
+
+[![CI](https://github.com/Plasius-LTD/graph-client-react/actions/workflows/ci.yml/badge.svg)](https://github.com/Plasius-LTD/graph-client-react/actions/workflows/ci.yml)
+[![CD](https://github.com/Plasius-LTD/graph-client-react/actions/workflows/cd.yml/badge.svg)](https://github.com/Plasius-LTD/graph-client-react/actions/workflows/cd.yml)
+
+React bindings for `@plasius/graph-client-core` query and mutation workflows.
+
+Apache-2.0. ESM + CJS builds. TypeScript types included.
+
+---
+
+## Requirements
+
+- Node.js 24+ (matches `.nvmrc` and CI/CD)
+- React 19 (`peerDependencies`)
+- `@plasius/graph-client-core`
+
+---
 
 ## Installation
 
-npm install @plasius/graph-client-react
+```bash
+npm install @plasius/graph-client-react @plasius/graph-client-core
+```
+
+---
+
+## Exports
+
+```ts
+import {
+  GraphClientProvider,
+  useGraphClient,
+  useGraphQuery,
+  useGraphMutation,
+  type UseGraphQueryOptions,
+  type UseGraphQueryState,
+  type UseGraphMutationOptions,
+  type GraphMutationClient,
+} from "@plasius/graph-client-react";
+```
+
+---
+
+## Quick Start
+
+```tsx
+import { GraphClient } from "@plasius/graph-client-core";
+import { GraphClientProvider, useGraphQuery } from "@plasius/graph-client-react";
+
+const client = new GraphClient({ transport: { async fetch() { return { data: { ok: true }, version: 1 }; } } });
+
+function Profile() {
+  const { data, loading, revalidating, error, refresh } = useGraphQuery(
+    {
+      requests: [{ resolver: "user.profile", key: "user:1" }],
+    },
+    { retryAttempts: 1, retryDelayMs: 25 },
+  );
+
+  if (loading) return <p>Loading</p>;
+  if (error) return <p>{error.message}</p>;
+
+  return (
+    <button onClick={() => void refresh()}>
+      {revalidating ? "Refreshing..." : JSON.stringify(data?.results)}
+    </button>
+  );
+}
+
+export function App() {
+  return (
+    <GraphClientProvider client={client}>
+      <Profile />
+    </GraphClientProvider>
+  );
+}
+```
+
+---
 
 ## Development
 
+```bash
+npm run clean
 npm install
+npm run lint
+npm run typecheck
+npm run test:coverage
 npm run build
-npm test
+```
+
+---
+
+## Query State Mapping
+
+- `loading`: first request with no cached hook data.
+- `revalidating`: refresh/rerender request when prior hook data exists.
+- `status`: `"loading" | "success" | "error"` terminal state for last request.
+- `error`: normalized to `Error`.
+
+Suspense is intentionally disabled in current package scope (see ADR-0003). Passing `suspense: true` to `useGraphQuery` throws.
+
+Both hooks support optional `telemetry` (from `TelemetrySink`) to emit analytics signals:
+
+- Query: `graph.react.query.run`, `graph.react.query.success`, `graph.react.query.retry`, `graph.react.query.error`
+- Mutation: `graph.react.mutation.success`, `graph.react.mutation.error`
+
+---
 
 ## Architecture
 
-- ADR documents are in docs/adrs/.
-- Cross-package architecture is tracked in plasius-ltd-site/docs/adrs/adr-0020 through adr-0024.
+- Package ADRs: [`docs/adrs`](./docs/adrs)
+- Cross-package ADRs: `plasius-ltd-site/docs/adrs/adr-0020` to `adr-0024`
+
+---
 
 ## License
 
-Apache-2.0
+Licensed under the [Apache-2.0 License](./LICENSE).

package/dist/index.cjs

@@ -48,24 +48,98 @@ function GraphClientProvider(props) {
 
 // src/hooks.ts
 var import_react3 = require("react");
-var useGraphQuery = (query) => {
+var wait = async (delayMs) => {
+  if (delayMs <= 0) {
+    return;
+  }
+  await new Promise((resolve) => {
+    setTimeout(resolve, delayMs);
+  });
+};
+var useGraphQuery = (query, options = {}) => {
   const client = useGraphClient();
+  const retryAttempts = Math.max(0, options.retryAttempts ?? 0);
+  const retryDelayMs = Math.max(0, options.retryDelayMs ?? 0);
+  const telemetry = options.telemetry;
+  if (options.suspense) {
+    throw new Error("Suspense mode is not supported by useGraphQuery. Use loading/error/revalidating state mapping.");
+  }
   const [data, setData] = (0, import_react3.useState)(null);
+  const dataRef = (0, import_react3.useRef)(null);
   const [error, setError] = (0, import_react3.useState)(null);
   const [loading, setLoading] = (0, import_react3.useState)(true);
+  const [revalidating, setRevalidating] = (0, import_react3.useState)(false);
+  const [status, setStatus] = (0, import_react3.useState)("loading");
+  (0, import_react3.useEffect)(() => {
+    dataRef.current = data;
+  }, [data]);
   const run = (0, import_react3.useCallback)(async (forceRefresh = false) => {
-    setLoading(true);
+    const startedAt = Date.now();
+    const hasExistingData = dataRef.current !== null;
+    setLoading(!hasExistingData);
+    setRevalidating(hasExistingData);
+    if (!hasExistingData) {
+      setStatus("loading");
+    }
+    telemetry?.metric({
+      name: "graph.react.query.run",
+      value: 1,
+      unit: "count",
+      tags: {
+        forceRefresh: forceRefresh ? "true" : "false",
+        hasExistingData: hasExistingData ? "true" : "false"
+      }
+    });
     setError(null);
-    try {
-      const result = await client.query(query, { allowStale: true, forceRefresh });
-      setData(result);
-    } catch (queryError) {
-      const resolvedError = queryError instanceof Error ? queryError : new Error("Graph query failed");
-      setError(resolvedError);
-    } finally {
-      setLoading(false);
+    for (let attempt = 0; attempt <= retryAttempts; attempt += 1) {
+      try {
+        const result = await client.query(query, { allowStale: true, forceRefresh });
+        dataRef.current = result;
+        setData(result);
+        setStatus("success");
+        setLoading(false);
+        setRevalidating(false);
+        telemetry?.metric({
+          name: "graph.react.query.success",
+          value: Date.now() - startedAt,
+          unit: "ms",
+          tags: {
+            attempt: String(attempt + 1)
+          }
+        });
+        return;
+      } catch (queryError) {
+        const resolvedError = queryError instanceof Error ? queryError : new Error("Graph query failed");
+        const hasRetriesRemaining = attempt < retryAttempts;
+        if (!hasRetriesRemaining) {
+          setError(resolvedError);
+          setStatus("error");
+          setLoading(false);
+          setRevalidating(false);
+          telemetry?.metric({
+            name: "graph.react.query.error",
+            value: 1,
+            unit: "count"
+          });
+          telemetry?.error({
+            message: resolvedError.message,
+            source: "graph-client-react.useGraphQuery",
+            code: "GRAPH_REACT_QUERY_FAILED"
+          });
+          return;
+        }
+        telemetry?.metric({
+          name: "graph.react.query.retry",
+          value: 1,
+          unit: "count",
+          tags: {
+            attempt: String(attempt + 1)
+          }
+        });
+        await wait(retryDelayMs);
+      }
     }
-  }, [client, query]);
+  }, [client, query, retryAttempts, retryDelayMs, telemetry]);
   (0, import_react3.useEffect)(() => {
     void run(false);
   }, [run]);
@@ -73,26 +147,47 @@ var useGraphQuery = (query) => {
     await run(true);
   }, [run]);
   return (0, import_react3.useMemo)(
-    () => ({ data, error, loading, refresh }),
-    [data, error, loading, refresh]
+    () => ({ data, error, loading, revalidating, status, refresh }),
+    [data, error, loading, revalidating, status, refresh]
   );
 };
-var useGraphMutation = (mutationClient) => {
+var useGraphMutation = (mutationClient, options = {}) => {
+  const telemetry = options.telemetry;
   const [loading, setLoading] = (0, import_react3.useState)(false);
   const [error, setError] = (0, import_react3.useState)(null);
   const mutate = (0, import_react3.useCallback)(async (command) => {
+    const startedAt = Date.now();
     setLoading(true);
     setError(null);
     try {
-      return await mutationClient.write(command);
+      const operation = await mutationClient.write(command);
+      telemetry?.metric({
+        name: "graph.react.mutation.success",
+        value: Date.now() - startedAt,
+        unit: "ms",
+        tags: {
+          state: operation.state
+        }
+      });
+      return operation;
     } catch (mutationError) {
       const resolvedError = mutationError instanceof Error ? mutationError : new Error("Graph mutation failed");
       setError(resolvedError);
+      telemetry?.metric({
+        name: "graph.react.mutation.error",
+        value: 1,
+        unit: "count"
+      });
+      telemetry?.error({
+        message: resolvedError.message,
+        source: "graph-client-react.useGraphMutation",
+        code: "GRAPH_REACT_MUTATION_FAILED"
+      });
       throw resolvedError;
     } finally {
       setLoading(false);
     }
-  }, [mutationClient]);
+  }, [mutationClient, telemetry]);
   return {
     mutate,
     loading,

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/context.ts","../src/provider.ts","../src/hooks.ts"],"sourcesContent":["export * from \"./context.js\";\nexport * from \"./provider.js\";\nexport * from \"./hooks.js\";\n","import { createContext, useContext } from \"react\";\n\nimport type { GraphClient } from \"@plasius/graph-client-core\";\n\nexport const GraphClientContext = createContext<GraphClient | null>(null);\n\nexport const useGraphClient = (): GraphClient => {\n  const client = useContext(GraphClientContext);\n  if (!client) {\n    throw new Error(\"GraphClientContext is missing. Wrap your tree in GraphClientProvider.\");\n  }\n\n  return client;\n};\n","import { createElement, type ReactNode } from \"react\";\n\nimport type { GraphClient } from \"@plasius/graph-client-core\";\nimport { GraphClientContext } from \"./context.js\";\n\nexport interface GraphClientProviderProps {\n  client: GraphClient;\n  children: ReactNode;\n}\n\nexport function GraphClientProvider(props: GraphClientProviderProps) {\n  const { client, children } = props;\n  return createElement(GraphClientContext.Provider, { value: client }, children);\n}\n","import { useCallback, useEffect, useMemo, useState } from \"react\";\n\nimport type { GraphQuery, GraphQueryResult, WriteCommand, WriteOperation } from \"@plasius/graph-contracts\";\nimport { useGraphClient } from \"./context.js\";\n\nexport interface UseGraphQueryState {\n  data: GraphQueryResult | null;\n  error: Error | null;\n  loading: boolean;\n  refresh: () => Promise<void>;\n}\n\nexport const useGraphQuery = (query: GraphQuery): UseGraphQueryState => {\n  const client = useGraphClient();\n  const [data, setData] = useState<GraphQueryResult | null>(null);\n  const [error, setError] = useState<Error | null>(null);\n  const [loading, setLoading] = useState<boolean>(true);\n\n  const run = useCallback(async (forceRefresh = false) => {\n    setLoading(true);\n    setError(null);\n    try {\n      const result = await client.query(query, { allowStale: true, forceRefresh });\n      setData(result);\n    } catch (queryError) {\n      const resolvedError = queryError instanceof Error ? queryError : new Error(\"Graph query failed\");\n      setError(resolvedError);\n    } finally {\n      setLoading(false);\n    }\n  }, [client, query]);\n\n  useEffect(() => {\n    void run(false);\n  }, [run]);\n\n  const refresh = useCallback(async () => {\n    await run(true);\n  }, [run]);\n\n  return useMemo(\n    () => ({ data, error, loading, refresh }),\n    [data, error, loading, refresh],\n  );\n};\n\nexport interface GraphMutationClient {\n  write(command: WriteCommand): Promise<WriteOperation>;\n}\n\nexport const useGraphMutation = (mutationClient: GraphMutationClient) => {\n  const [loading, setLoading] = useState(false);\n  const [error, setError] = useState<Error | null>(null);\n\n  const mutate = useCallback(async (command: WriteCommand) => {\n    setLoading(true);\n    setError(null);\n    try {\n      return await mutationClient.write(command);\n    } catch (mutationError) {\n      const resolvedError = mutationError instanceof Error ? mutationError : new Error(\"Graph mutation failed\");\n      setError(resolvedError);\n      throw resolvedError;\n    } finally {\n      setLoading(false);\n    }\n  }, [mutationClient]);\n\n  return {\n    mutate,\n    loading,\n    error,\n  };\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,mBAA0C;AAInC,IAAM,yBAAqB,4BAAkC,IAAI;AAEjE,IAAM,iBAAiB,MAAmB;AAC/C,QAAM,aAAS,yBAAW,kBAAkB;AAC5C,MAAI,CAAC,QAAQ;AACX,UAAM,IAAI,MAAM,uEAAuE;AAAA,EACzF;AAEA,SAAO;AACT;;;ACbA,IAAAA,gBAA8C;AAUvC,SAAS,oBAAoB,OAAiC;AACnE,QAAM,EAAE,QAAQ,SAAS,IAAI;AAC7B,aAAO,6BAAc,mBAAmB,UAAU,EAAE,OAAO,OAAO,GAAG,QAAQ;AAC/E;;;ACbA,IAAAC,gBAA0D;AAYnD,IAAM,gBAAgB,CAAC,UAA0C;AACtE,QAAM,SAAS,eAAe;AAC9B,QAAM,CAAC,MAAM,OAAO,QAAI,wBAAkC,IAAI;AAC9D,QAAM,CAAC,OAAO,QAAQ,QAAI,wBAAuB,IAAI;AACrD,QAAM,CAAC,SAAS,UAAU,QAAI,wBAAkB,IAAI;AAEpD,QAAM,UAAM,2BAAY,OAAO,eAAe,UAAU;AACtD,eAAW,IAAI;AACf,aAAS,IAAI;AACb,QAAI;AACF,YAAM,SAAS,MAAM,OAAO,MAAM,OAAO,EAAE,YAAY,MAAM,aAAa,CAAC;AAC3E,cAAQ,MAAM;AAAA,IAChB,SAAS,YAAY;AACnB,YAAM,gBAAgB,sBAAsB,QAAQ,aAAa,IAAI,MAAM,oBAAoB;AAC/F,eAAS,aAAa;AAAA,IACxB,UAAE;AACA,iBAAW,KAAK;AAAA,IAClB;AAAA,EACF,GAAG,CAAC,QAAQ,KAAK,CAAC;AAElB,+BAAU,MAAM;AACd,SAAK,IAAI,KAAK;AAAA,EAChB,GAAG,CAAC,GAAG,CAAC;AAER,QAAM,cAAU,2BAAY,YAAY;AACtC,UAAM,IAAI,IAAI;AAAA,EAChB,GAAG,CAAC,GAAG,CAAC;AAER,aAAO;AAAA,IACL,OAAO,EAAE,MAAM,OAAO,SAAS,QAAQ;AAAA,IACvC,CAAC,MAAM,OAAO,SAAS,OAAO;AAAA,EAChC;AACF;AAMO,IAAM,mBAAmB,CAAC,mBAAwC;AACvE,QAAM,CAAC,SAAS,UAAU,QAAI,wBAAS,KAAK;AAC5C,QAAM,CAAC,OAAO,QAAQ,QAAI,wBAAuB,IAAI;AAErD,QAAM,aAAS,2BAAY,OAAO,YAA0B;AAC1D,eAAW,IAAI;AACf,aAAS,IAAI;AACb,QAAI;AACF,aAAO,MAAM,eAAe,MAAM,OAAO;AAAA,IAC3C,SAAS,eAAe;AACtB,YAAM,gBAAgB,yBAAyB,QAAQ,gBAAgB,IAAI,MAAM,uBAAuB;AACxG,eAAS,aAAa;AACtB,YAAM;AAAA,IACR,UAAE;AACA,iBAAW,KAAK;AAAA,IAClB;AAAA,EACF,GAAG,CAAC,cAAc,CAAC;AAEnB,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;","names":["import_react","import_react"]}
+{"version":3,"sources":["../src/index.ts","../src/context.ts","../src/provider.ts","../src/hooks.ts"],"sourcesContent":["export * from \"./context.js\";\nexport * from \"./provider.js\";\nexport * from \"./hooks.js\";\n","import { createContext, useContext } from \"react\";\n\nimport type { GraphClient } from \"@plasius/graph-client-core\";\n\nexport const GraphClientContext = createContext<GraphClient | null>(null);\n\nexport const useGraphClient = (): GraphClient => {\n  const client = useContext(GraphClientContext);\n  if (!client) {\n    throw new Error(\"GraphClientContext is missing. Wrap your tree in GraphClientProvider.\");\n  }\n\n  return client;\n};\n","import { createElement, type ReactNode } from \"react\";\n\nimport type { GraphClient } from \"@plasius/graph-client-core\";\nimport { GraphClientContext } from \"./context.js\";\n\nexport interface GraphClientProviderProps {\n  client: GraphClient;\n  children: ReactNode;\n}\n\nexport function GraphClientProvider(props: GraphClientProviderProps) {\n  const { client, children } = props;\n  return createElement(GraphClientContext.Provider, { value: client }, children);\n}\n","import { useCallback, useEffect, useMemo, useRef, useState } from \"react\";\n\nimport type { GraphQuery, GraphQueryResult, TelemetrySink, WriteCommand, WriteOperation } from \"@plasius/graph-contracts\";\nimport { useGraphClient } from \"./context.js\";\n\nexport interface UseGraphQueryState {\n  data: GraphQueryResult | null;\n  error: Error | null;\n  loading: boolean;\n  revalidating: boolean;\n  status: \"loading\" | \"success\" | \"error\";\n  refresh: () => Promise<void>;\n}\n\nexport interface UseGraphQueryOptions {\n  retryAttempts?: number;\n  retryDelayMs?: number;\n  suspense?: boolean;\n  telemetry?: TelemetrySink;\n}\n\nconst wait = async (delayMs: number): Promise<void> => {\n  if (delayMs <= 0) {\n    return;\n  }\n\n  await new Promise((resolve) => {\n    setTimeout(resolve, delayMs);\n  });\n};\n\nexport const useGraphQuery = (query: GraphQuery, options: UseGraphQueryOptions = {}): UseGraphQueryState => {\n  const client = useGraphClient();\n  const retryAttempts = Math.max(0, options.retryAttempts ?? 0);\n  const retryDelayMs = Math.max(0, options.retryDelayMs ?? 0);\n  const telemetry = options.telemetry;\n  if (options.suspense) {\n    throw new Error(\"Suspense mode is not supported by useGraphQuery. Use loading/error/revalidating state mapping.\");\n  }\n\n  const [data, setData] = useState<GraphQueryResult | null>(null);\n  const dataRef = useRef<GraphQueryResult | null>(null);\n  const [error, setError] = useState<Error | null>(null);\n  const [loading, setLoading] = useState<boolean>(true);\n  const [revalidating, setRevalidating] = useState<boolean>(false);\n  const [status, setStatus] = useState<\"loading\" | \"success\" | \"error\">(\"loading\");\n\n  useEffect(() => {\n    dataRef.current = data;\n  }, [data]);\n\n  const run = useCallback(async (forceRefresh = false) => {\n    const startedAt = Date.now();\n    const hasExistingData = dataRef.current !== null;\n    setLoading(!hasExistingData);\n    setRevalidating(hasExistingData);\n    if (!hasExistingData) {\n      setStatus(\"loading\");\n    }\n    telemetry?.metric({\n      name: \"graph.react.query.run\",\n      value: 1,\n      unit: \"count\",\n      tags: {\n        forceRefresh: forceRefresh ? \"true\" : \"false\",\n        hasExistingData: hasExistingData ? \"true\" : \"false\",\n      },\n    });\n    setError(null);\n    for (let attempt = 0; attempt <= retryAttempts; attempt += 1) {\n      try {\n        const result = await client.query(query, { allowStale: true, forceRefresh });\n        dataRef.current = result;\n        setData(result);\n        setStatus(\"success\");\n        setLoading(false);\n        setRevalidating(false);\n        telemetry?.metric({\n          name: \"graph.react.query.success\",\n          value: Date.now() - startedAt,\n          unit: \"ms\",\n          tags: {\n            attempt: String(attempt + 1),\n          },\n        });\n        return;\n      } catch (queryError) {\n        const resolvedError = queryError instanceof Error ? queryError : new Error(\"Graph query failed\");\n        const hasRetriesRemaining = attempt < retryAttempts;\n        if (!hasRetriesRemaining) {\n          setError(resolvedError);\n          setStatus(\"error\");\n          setLoading(false);\n          setRevalidating(false);\n          telemetry?.metric({\n            name: \"graph.react.query.error\",\n            value: 1,\n            unit: \"count\",\n          });\n          telemetry?.error({\n            message: resolvedError.message,\n            source: \"graph-client-react.useGraphQuery\",\n            code: \"GRAPH_REACT_QUERY_FAILED\",\n          });\n          return;\n        }\n\n        telemetry?.metric({\n          name: \"graph.react.query.retry\",\n          value: 1,\n          unit: \"count\",\n          tags: {\n            attempt: String(attempt + 1),\n          },\n        });\n        await wait(retryDelayMs);\n      }\n    }\n  }, [client, query, retryAttempts, retryDelayMs, telemetry]);\n\n  useEffect(() => {\n    void run(false);\n  }, [run]);\n\n  const refresh = useCallback(async () => {\n    await run(true);\n  }, [run]);\n\n  return useMemo(\n    () => ({ data, error, loading, revalidating, status, refresh }),\n    [data, error, loading, revalidating, status, refresh],\n  );\n};\n\nexport interface GraphMutationClient {\n  write(command: WriteCommand): Promise<WriteOperation>;\n}\n\nexport interface UseGraphMutationOptions {\n  telemetry?: TelemetrySink;\n}\n\nexport const useGraphMutation = (mutationClient: GraphMutationClient, options: UseGraphMutationOptions = {}) => {\n  const telemetry = options.telemetry;\n  const [loading, setLoading] = useState(false);\n  const [error, setError] = useState<Error | null>(null);\n\n  const mutate = useCallback(async (command: WriteCommand) => {\n    const startedAt = Date.now();\n    setLoading(true);\n    setError(null);\n    try {\n      const operation = await mutationClient.write(command);\n      telemetry?.metric({\n        name: \"graph.react.mutation.success\",\n        value: Date.now() - startedAt,\n        unit: \"ms\",\n        tags: {\n          state: operation.state,\n        },\n      });\n      return operation;\n    } catch (mutationError) {\n      const resolvedError = mutationError instanceof Error ? mutationError : new Error(\"Graph mutation failed\");\n      setError(resolvedError);\n      telemetry?.metric({\n        name: \"graph.react.mutation.error\",\n        value: 1,\n        unit: \"count\",\n      });\n      telemetry?.error({\n        message: resolvedError.message,\n        source: \"graph-client-react.useGraphMutation\",\n        code: \"GRAPH_REACT_MUTATION_FAILED\",\n      });\n      throw resolvedError;\n    } finally {\n      setLoading(false);\n    }\n  }, [mutationClient, telemetry]);\n\n  return {\n    mutate,\n    loading,\n    error,\n  };\n};\n"],"mappings":"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","names":["import_react","import_react"]}

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
 import { GraphClient } from '@plasius/graph-client-core';
-import { WriteCommand, WriteOperation, GraphQueryResult, GraphQuery } from '@plasius/graph-contracts';
+import { WriteCommand, WriteOperation, TelemetrySink, GraphQueryResult, GraphQuery } from '@plasius/graph-contracts';
 
 declare const GraphClientContext: react.Context<GraphClient | null>;
 declare const useGraphClient: () => GraphClient;
@@ -16,16 +16,27 @@ interface UseGraphQueryState {
     data: GraphQueryResult | null;
     error: Error | null;
     loading: boolean;
+    revalidating: boolean;
+    status: "loading" | "success" | "error";
     refresh: () => Promise<void>;
 }
-declare const useGraphQuery: (query: GraphQuery) => UseGraphQueryState;
+interface UseGraphQueryOptions {
+    retryAttempts?: number;
+    retryDelayMs?: number;
+    suspense?: boolean;
+    telemetry?: TelemetrySink;
+}
+declare const useGraphQuery: (query: GraphQuery, options?: UseGraphQueryOptions) => UseGraphQueryState;
 interface GraphMutationClient {
     write(command: WriteCommand): Promise<WriteOperation>;
 }
-declare const useGraphMutation: (mutationClient: GraphMutationClient) => {
+interface UseGraphMutationOptions {
+    telemetry?: TelemetrySink;
+}
+declare const useGraphMutation: (mutationClient: GraphMutationClient, options?: UseGraphMutationOptions) => {
     mutate: (command: WriteCommand) => Promise<WriteOperation>;
     loading: boolean;
     error: Error | null;
 };
 
-export { GraphClientContext, GraphClientProvider, type GraphClientProviderProps, type GraphMutationClient, type UseGraphQueryState, useGraphClient, useGraphMutation, useGraphQuery };
+export { GraphClientContext, GraphClientProvider, type GraphClientProviderProps, type GraphMutationClient, type UseGraphMutationOptions, type UseGraphQueryOptions, type UseGraphQueryState, useGraphClient, useGraphMutation, useGraphQuery };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
 import { GraphClient } from '@plasius/graph-client-core';
-import { WriteCommand, WriteOperation, GraphQueryResult, GraphQuery } from '@plasius/graph-contracts';
+import { WriteCommand, WriteOperation, TelemetrySink, GraphQueryResult, GraphQuery } from '@plasius/graph-contracts';
 
 declare const GraphClientContext: react.Context<GraphClient | null>;
 declare const useGraphClient: () => GraphClient;
@@ -16,16 +16,27 @@ interface UseGraphQueryState {
     data: GraphQueryResult | null;
     error: Error | null;
     loading: boolean;
+    revalidating: boolean;
+    status: "loading" | "success" | "error";
     refresh: () => Promise<void>;
 }
-declare const useGraphQuery: (query: GraphQuery) => UseGraphQueryState;
+interface UseGraphQueryOptions {
+    retryAttempts?: number;
+    retryDelayMs?: number;
+    suspense?: boolean;
+    telemetry?: TelemetrySink;
+}
+declare const useGraphQuery: (query: GraphQuery, options?: UseGraphQueryOptions) => UseGraphQueryState;
 interface GraphMutationClient {
     write(command: WriteCommand): Promise<WriteOperation>;
 }
-declare const useGraphMutation: (mutationClient: GraphMutationClient) => {
+interface UseGraphMutationOptions {
+    telemetry?: TelemetrySink;
+}
+declare const useGraphMutation: (mutationClient: GraphMutationClient, options?: UseGraphMutationOptions) => {
     mutate: (command: WriteCommand) => Promise<WriteOperation>;
     loading: boolean;
     error: Error | null;
 };
 
-export { GraphClientContext, GraphClientProvider, type GraphClientProviderProps, type GraphMutationClient, type UseGraphQueryState, useGraphClient, useGraphMutation, useGraphQuery };
+export { GraphClientContext, GraphClientProvider, type GraphClientProviderProps, type GraphMutationClient, type UseGraphMutationOptions, type UseGraphQueryOptions, type UseGraphQueryState, useGraphClient, useGraphMutation, useGraphQuery };

package/dist/index.js

@@ -17,25 +17,99 @@ function GraphClientProvider(props) {
 }
 
 // src/hooks.ts
-import { useCallback, useEffect, useMemo, useState } from "react";
-var useGraphQuery = (query) => {
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+var wait = async (delayMs) => {
+  if (delayMs <= 0) {
+    return;
+  }
+  await new Promise((resolve) => {
+    setTimeout(resolve, delayMs);
+  });
+};
+var useGraphQuery = (query, options = {}) => {
   const client = useGraphClient();
+  const retryAttempts = Math.max(0, options.retryAttempts ?? 0);
+  const retryDelayMs = Math.max(0, options.retryDelayMs ?? 0);
+  const telemetry = options.telemetry;
+  if (options.suspense) {
+    throw new Error("Suspense mode is not supported by useGraphQuery. Use loading/error/revalidating state mapping.");
+  }
   const [data, setData] = useState(null);
+  const dataRef = useRef(null);
   const [error, setError] = useState(null);
   const [loading, setLoading] = useState(true);
+  const [revalidating, setRevalidating] = useState(false);
+  const [status, setStatus] = useState("loading");
+  useEffect(() => {
+    dataRef.current = data;
+  }, [data]);
   const run = useCallback(async (forceRefresh = false) => {
-    setLoading(true);
+    const startedAt = Date.now();
+    const hasExistingData = dataRef.current !== null;
+    setLoading(!hasExistingData);
+    setRevalidating(hasExistingData);
+    if (!hasExistingData) {
+      setStatus("loading");
+    }
+    telemetry?.metric({
+      name: "graph.react.query.run",
+      value: 1,
+      unit: "count",
+      tags: {
+        forceRefresh: forceRefresh ? "true" : "false",
+        hasExistingData: hasExistingData ? "true" : "false"
+      }
+    });
     setError(null);
-    try {
-      const result = await client.query(query, { allowStale: true, forceRefresh });
-      setData(result);
-    } catch (queryError) {
-      const resolvedError = queryError instanceof Error ? queryError : new Error("Graph query failed");
-      setError(resolvedError);
-    } finally {
-      setLoading(false);
+    for (let attempt = 0; attempt <= retryAttempts; attempt += 1) {
+      try {
+        const result = await client.query(query, { allowStale: true, forceRefresh });
+        dataRef.current = result;
+        setData(result);
+        setStatus("success");
+        setLoading(false);
+        setRevalidating(false);
+        telemetry?.metric({
+          name: "graph.react.query.success",
+          value: Date.now() - startedAt,
+          unit: "ms",
+          tags: {
+            attempt: String(attempt + 1)
+          }
+        });
+        return;
+      } catch (queryError) {
+        const resolvedError = queryError instanceof Error ? queryError : new Error("Graph query failed");
+        const hasRetriesRemaining = attempt < retryAttempts;
+        if (!hasRetriesRemaining) {
+          setError(resolvedError);
+          setStatus("error");
+          setLoading(false);
+          setRevalidating(false);
+          telemetry?.metric({
+            name: "graph.react.query.error",
+            value: 1,
+            unit: "count"
+          });
+          telemetry?.error({
+            message: resolvedError.message,
+            source: "graph-client-react.useGraphQuery",
+            code: "GRAPH_REACT_QUERY_FAILED"
+          });
+          return;
+        }
+        telemetry?.metric({
+          name: "graph.react.query.retry",
+          value: 1,
+          unit: "count",
+          tags: {
+            attempt: String(attempt + 1)
+          }
+        });
+        await wait(retryDelayMs);
+      }
     }
-  }, [client, query]);
+  }, [client, query, retryAttempts, retryDelayMs, telemetry]);
   useEffect(() => {
     void run(false);
   }, [run]);
@@ -43,26 +117,47 @@ var useGraphQuery = (query) => {
     await run(true);
   }, [run]);
   return useMemo(
-    () => ({ data, error, loading, refresh }),
-    [data, error, loading, refresh]
+    () => ({ data, error, loading, revalidating, status, refresh }),
+    [data, error, loading, revalidating, status, refresh]
   );
 };
-var useGraphMutation = (mutationClient) => {
+var useGraphMutation = (mutationClient, options = {}) => {
+  const telemetry = options.telemetry;
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState(null);
   const mutate = useCallback(async (command) => {
+    const startedAt = Date.now();
     setLoading(true);
     setError(null);
     try {
-      return await mutationClient.write(command);
+      const operation = await mutationClient.write(command);
+      telemetry?.metric({
+        name: "graph.react.mutation.success",
+        value: Date.now() - startedAt,
+        unit: "ms",
+        tags: {
+          state: operation.state
+        }
+      });
+      return operation;
     } catch (mutationError) {
       const resolvedError = mutationError instanceof Error ? mutationError : new Error("Graph mutation failed");
       setError(resolvedError);
+      telemetry?.metric({
+        name: "graph.react.mutation.error",
+        value: 1,
+        unit: "count"
+      });
+      telemetry?.error({
+        message: resolvedError.message,
+        source: "graph-client-react.useGraphMutation",
+        code: "GRAPH_REACT_MUTATION_FAILED"
+      });
       throw resolvedError;
     } finally {
       setLoading(false);
     }
-  }, [mutationClient]);
+  }, [mutationClient, telemetry]);
   return {
     mutate,
     loading,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/context.ts","../src/provider.ts","../src/hooks.ts"],"sourcesContent":["import { createContext, useContext } from \"react\";\n\nimport type { GraphClient } from \"@plasius/graph-client-core\";\n\nexport const GraphClientContext = createContext<GraphClient | null>(null);\n\nexport const useGraphClient = (): GraphClient => {\n  const client = useContext(GraphClientContext);\n  if (!client) {\n    throw new Error(\"GraphClientContext is missing. Wrap your tree in GraphClientProvider.\");\n  }\n\n  return client;\n};\n","import { createElement, type ReactNode } from \"react\";\n\nimport type { GraphClient } from \"@plasius/graph-client-core\";\nimport { GraphClientContext } from \"./context.js\";\n\nexport interface GraphClientProviderProps {\n  client: GraphClient;\n  children: ReactNode;\n}\n\nexport function GraphClientProvider(props: GraphClientProviderProps) {\n  const { client, children } = props;\n  return createElement(GraphClientContext.Provider, { value: client }, children);\n}\n","import { useCallback, useEffect, useMemo, useState } from \"react\";\n\nimport type { GraphQuery, GraphQueryResult, WriteCommand, WriteOperation } from \"@plasius/graph-contracts\";\nimport { useGraphClient } from \"./context.js\";\n\nexport interface UseGraphQueryState {\n  data: GraphQueryResult | null;\n  error: Error | null;\n  loading: boolean;\n  refresh: () => Promise<void>;\n}\n\nexport const useGraphQuery = (query: GraphQuery): UseGraphQueryState => {\n  const client = useGraphClient();\n  const [data, setData] = useState<GraphQueryResult | null>(null);\n  const [error, setError] = useState<Error | null>(null);\n  const [loading, setLoading] = useState<boolean>(true);\n\n  const run = useCallback(async (forceRefresh = false) => {\n    setLoading(true);\n    setError(null);\n    try {\n      const result = await client.query(query, { allowStale: true, forceRefresh });\n      setData(result);\n    } catch (queryError) {\n      const resolvedError = queryError instanceof Error ? queryError : new Error(\"Graph query failed\");\n      setError(resolvedError);\n    } finally {\n      setLoading(false);\n    }\n  }, [client, query]);\n\n  useEffect(() => {\n    void run(false);\n  }, [run]);\n\n  const refresh = useCallback(async () => {\n    await run(true);\n  }, [run]);\n\n  return useMemo(\n    () => ({ data, error, loading, refresh }),\n    [data, error, loading, refresh],\n  );\n};\n\nexport interface GraphMutationClient {\n  write(command: WriteCommand): Promise<WriteOperation>;\n}\n\nexport const useGraphMutation = (mutationClient: GraphMutationClient) => {\n  const [loading, setLoading] = useState(false);\n  const [error, setError] = useState<Error | null>(null);\n\n  const mutate = useCallback(async (command: WriteCommand) => {\n    setLoading(true);\n    setError(null);\n    try {\n      return await mutationClient.write(command);\n    } catch (mutationError) {\n      const resolvedError = mutationError instanceof Error ? mutationError : new Error(\"Graph mutation failed\");\n      setError(resolvedError);\n      throw resolvedError;\n    } finally {\n      setLoading(false);\n    }\n  }, [mutationClient]);\n\n  return {\n    mutate,\n    loading,\n    error,\n  };\n};\n"],"mappings":";AAAA,SAAS,eAAe,kBAAkB;AAInC,IAAM,qBAAqB,cAAkC,IAAI;AAEjE,IAAM,iBAAiB,MAAmB;AAC/C,QAAM,SAAS,WAAW,kBAAkB;AAC5C,MAAI,CAAC,QAAQ;AACX,UAAM,IAAI,MAAM,uEAAuE;AAAA,EACzF;AAEA,SAAO;AACT;;;ACbA,SAAS,qBAAqC;AAUvC,SAAS,oBAAoB,OAAiC;AACnE,QAAM,EAAE,QAAQ,SAAS,IAAI;AAC7B,SAAO,cAAc,mBAAmB,UAAU,EAAE,OAAO,OAAO,GAAG,QAAQ;AAC/E;;;ACbA,SAAS,aAAa,WAAW,SAAS,gBAAgB;AAYnD,IAAM,gBAAgB,CAAC,UAA0C;AACtE,QAAM,SAAS,eAAe;AAC9B,QAAM,CAAC,MAAM,OAAO,IAAI,SAAkC,IAAI;AAC9D,QAAM,CAAC,OAAO,QAAQ,IAAI,SAAuB,IAAI;AACrD,QAAM,CAAC,SAAS,UAAU,IAAI,SAAkB,IAAI;AAEpD,QAAM,MAAM,YAAY,OAAO,eAAe,UAAU;AACtD,eAAW,IAAI;AACf,aAAS,IAAI;AACb,QAAI;AACF,YAAM,SAAS,MAAM,OAAO,MAAM,OAAO,EAAE,YAAY,MAAM,aAAa,CAAC;AAC3E,cAAQ,MAAM;AAAA,IAChB,SAAS,YAAY;AACnB,YAAM,gBAAgB,sBAAsB,QAAQ,aAAa,IAAI,MAAM,oBAAoB;AAC/F,eAAS,aAAa;AAAA,IACxB,UAAE;AACA,iBAAW,KAAK;AAAA,IAClB;AAAA,EACF,GAAG,CAAC,QAAQ,KAAK,CAAC;AAElB,YAAU,MAAM;AACd,SAAK,IAAI,KAAK;AAAA,EAChB,GAAG,CAAC,GAAG,CAAC;AAER,QAAM,UAAU,YAAY,YAAY;AACtC,UAAM,IAAI,IAAI;AAAA,EAChB,GAAG,CAAC,GAAG,CAAC;AAER,SAAO;AAAA,IACL,OAAO,EAAE,MAAM,OAAO,SAAS,QAAQ;AAAA,IACvC,CAAC,MAAM,OAAO,SAAS,OAAO;AAAA,EAChC;AACF;AAMO,IAAM,mBAAmB,CAAC,mBAAwC;AACvE,QAAM,CAAC,SAAS,UAAU,IAAI,SAAS,KAAK;AAC5C,QAAM,CAAC,OAAO,QAAQ,IAAI,SAAuB,IAAI;AAErD,QAAM,SAAS,YAAY,OAAO,YAA0B;AAC1D,eAAW,IAAI;AACf,aAAS,IAAI;AACb,QAAI;AACF,aAAO,MAAM,eAAe,MAAM,OAAO;AAAA,IAC3C,SAAS,eAAe;AACtB,YAAM,gBAAgB,yBAAyB,QAAQ,gBAAgB,IAAI,MAAM,uBAAuB;AACxG,eAAS,aAAa;AACtB,YAAM;AAAA,IACR,UAAE;AACA,iBAAW,KAAK;AAAA,IAClB;AAAA,EACF,GAAG,CAAC,cAAc,CAAC;AAEnB,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../src/context.ts","../src/provider.ts","../src/hooks.ts"],"sourcesContent":["import { createContext, useContext } from \"react\";\n\nimport type { GraphClient } from \"@plasius/graph-client-core\";\n\nexport const GraphClientContext = createContext<GraphClient | null>(null);\n\nexport const useGraphClient = (): GraphClient => {\n  const client = useContext(GraphClientContext);\n  if (!client) {\n    throw new Error(\"GraphClientContext is missing. Wrap your tree in GraphClientProvider.\");\n  }\n\n  return client;\n};\n","import { createElement, type ReactNode } from \"react\";\n\nimport type { GraphClient } from \"@plasius/graph-client-core\";\nimport { GraphClientContext } from \"./context.js\";\n\nexport interface GraphClientProviderProps {\n  client: GraphClient;\n  children: ReactNode;\n}\n\nexport function GraphClientProvider(props: GraphClientProviderProps) {\n  const { client, children } = props;\n  return createElement(GraphClientContext.Provider, { value: client }, children);\n}\n","import { useCallback, useEffect, useMemo, useRef, useState } from \"react\";\n\nimport type { GraphQuery, GraphQueryResult, TelemetrySink, WriteCommand, WriteOperation } from \"@plasius/graph-contracts\";\nimport { useGraphClient } from \"./context.js\";\n\nexport interface UseGraphQueryState {\n  data: GraphQueryResult | null;\n  error: Error | null;\n  loading: boolean;\n  revalidating: boolean;\n  status: \"loading\" | \"success\" | \"error\";\n  refresh: () => Promise<void>;\n}\n\nexport interface UseGraphQueryOptions {\n  retryAttempts?: number;\n  retryDelayMs?: number;\n  suspense?: boolean;\n  telemetry?: TelemetrySink;\n}\n\nconst wait = async (delayMs: number): Promise<void> => {\n  if (delayMs <= 0) {\n    return;\n  }\n\n  await new Promise((resolve) => {\n    setTimeout(resolve, delayMs);\n  });\n};\n\nexport const useGraphQuery = (query: GraphQuery, options: UseGraphQueryOptions = {}): UseGraphQueryState => {\n  const client = useGraphClient();\n  const retryAttempts = Math.max(0, options.retryAttempts ?? 0);\n  const retryDelayMs = Math.max(0, options.retryDelayMs ?? 0);\n  const telemetry = options.telemetry;\n  if (options.suspense) {\n    throw new Error(\"Suspense mode is not supported by useGraphQuery. Use loading/error/revalidating state mapping.\");\n  }\n\n  const [data, setData] = useState<GraphQueryResult | null>(null);\n  const dataRef = useRef<GraphQueryResult | null>(null);\n  const [error, setError] = useState<Error | null>(null);\n  const [loading, setLoading] = useState<boolean>(true);\n  const [revalidating, setRevalidating] = useState<boolean>(false);\n  const [status, setStatus] = useState<\"loading\" | \"success\" | \"error\">(\"loading\");\n\n  useEffect(() => {\n    dataRef.current = data;\n  }, [data]);\n\n  const run = useCallback(async (forceRefresh = false) => {\n    const startedAt = Date.now();\n    const hasExistingData = dataRef.current !== null;\n    setLoading(!hasExistingData);\n    setRevalidating(hasExistingData);\n    if (!hasExistingData) {\n      setStatus(\"loading\");\n    }\n    telemetry?.metric({\n      name: \"graph.react.query.run\",\n      value: 1,\n      unit: \"count\",\n      tags: {\n        forceRefresh: forceRefresh ? \"true\" : \"false\",\n        hasExistingData: hasExistingData ? \"true\" : \"false\",\n      },\n    });\n    setError(null);\n    for (let attempt = 0; attempt <= retryAttempts; attempt += 1) {\n      try {\n        const result = await client.query(query, { allowStale: true, forceRefresh });\n        dataRef.current = result;\n        setData(result);\n        setStatus(\"success\");\n        setLoading(false);\n        setRevalidating(false);\n        telemetry?.metric({\n          name: \"graph.react.query.success\",\n          value: Date.now() - startedAt,\n          unit: \"ms\",\n          tags: {\n            attempt: String(attempt + 1),\n          },\n        });\n        return;\n      } catch (queryError) {\n        const resolvedError = queryError instanceof Error ? queryError : new Error(\"Graph query failed\");\n        const hasRetriesRemaining = attempt < retryAttempts;\n        if (!hasRetriesRemaining) {\n          setError(resolvedError);\n          setStatus(\"error\");\n          setLoading(false);\n          setRevalidating(false);\n          telemetry?.metric({\n            name: \"graph.react.query.error\",\n            value: 1,\n            unit: \"count\",\n          });\n          telemetry?.error({\n            message: resolvedError.message,\n            source: \"graph-client-react.useGraphQuery\",\n            code: \"GRAPH_REACT_QUERY_FAILED\",\n          });\n          return;\n        }\n\n        telemetry?.metric({\n          name: \"graph.react.query.retry\",\n          value: 1,\n          unit: \"count\",\n          tags: {\n            attempt: String(attempt + 1),\n          },\n        });\n        await wait(retryDelayMs);\n      }\n    }\n  }, [client, query, retryAttempts, retryDelayMs, telemetry]);\n\n  useEffect(() => {\n    void run(false);\n  }, [run]);\n\n  const refresh = useCallback(async () => {\n    await run(true);\n  }, [run]);\n\n  return useMemo(\n    () => ({ data, error, loading, revalidating, status, refresh }),\n    [data, error, loading, revalidating, status, refresh],\n  );\n};\n\nexport interface GraphMutationClient {\n  write(command: WriteCommand): Promise<WriteOperation>;\n}\n\nexport interface UseGraphMutationOptions {\n  telemetry?: TelemetrySink;\n}\n\nexport const useGraphMutation = (mutationClient: GraphMutationClient, options: UseGraphMutationOptions = {}) => {\n  const telemetry = options.telemetry;\n  const [loading, setLoading] = useState(false);\n  const [error, setError] = useState<Error | null>(null);\n\n  const mutate = useCallback(async (command: WriteCommand) => {\n    const startedAt = Date.now();\n    setLoading(true);\n    setError(null);\n    try {\n      const operation = await mutationClient.write(command);\n      telemetry?.metric({\n        name: \"graph.react.mutation.success\",\n        value: Date.now() - startedAt,\n        unit: \"ms\",\n        tags: {\n          state: operation.state,\n        },\n      });\n      return operation;\n    } catch (mutationError) {\n      const resolvedError = mutationError instanceof Error ? mutationError : new Error(\"Graph mutation failed\");\n      setError(resolvedError);\n      telemetry?.metric({\n        name: \"graph.react.mutation.error\",\n        value: 1,\n        unit: \"count\",\n      });\n      telemetry?.error({\n        message: resolvedError.message,\n        source: \"graph-client-react.useGraphMutation\",\n        code: \"GRAPH_REACT_MUTATION_FAILED\",\n      });\n      throw resolvedError;\n    } finally {\n      setLoading(false);\n    }\n  }, [mutationClient, telemetry]);\n\n  return {\n    mutate,\n    loading,\n    error,\n  };\n};\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plasius/graph-client-react",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "React bindings for @plasius/graph-client-core",
   "type": "module",
   "sideEffects": false,