@defjs/react 0.0.1-beta.1 → 0.0.2

package/README.md

@@ -1,8 +1,8 @@
 # @defjs/react
 
-Thin React adapter for `@defjs/core`. It provides an existing Defjs client through React Context.
+Thin React plugin for `@defjs/core`: it provides an application-owned client through React Context. It adds no query layer, cache, Suspense integration, or state management, and never creates, replaces, or disposes a client.
 
-Supports React 18+.
+Keeping SDK definitions in their own package means the SDK needs no React dependency. Requires React 18 or later; the published entry is marked `'use client'`.
 
 ## Install
 
@@ -10,95 +10,93 @@ Supports React 18+.
 bun add @defjs/core @defjs/react react
 ```
 
-The package is ESM and requires `@defjs/core` as a peer in the `^0.4.0` range. Its tarball retains this `README.md` and the repository `LICENSE`; repository-wide guides and examples remain outside the package.
+The package is ESM and requires `@defjs/core` as a peer in the `^0.5.0` range.
 
-## What this package does
-
-`ClientProvider` exposes the exact `Client` instance supplied by the application. `useClient()` reads the nearest provided instance.
-
-Client creation and configuration stay in `@defjs/core`. The adapter does not create, cache, replace, dispose, abort, or close anything on behalf of the application, and it does not add a query layer, Suspense integration, GraphQL client, or application state management.
-
-## Quick Start
-
-Define requests in a shared module:
+## Quick start
 
 ```tsx
-// api.ts
-import { defineRequest, struct } from '@defjs/core'
+// api.ts — reusable definition
+import { defineRequest, struct } from "@defjs/core";
 
 export const getUser = defineRequest({
-  method: 'GET',
-  path: '/users/:id',
-  input: struct.object({
-    path: struct.object({ id: struct.number() }),
-  }),
+  method: "GET",
+  path: "/users/:id",
+  input: struct.object({ id: struct.number() }),
+  builder: (input) => ({ path: input }),
   output: struct.object({ id: struct.number(), name: struct.string() }),
-})
+});
 ```
 
-Create and own the client at the application boundary, then provide it:
-
 ```tsx
 // app.tsx
-import { createClient, withEndpoint } from '@defjs/core'
-import { ClientProvider } from '@defjs/react'
-import { UserProfile } from './user-profile'
+import { createClient, withEndpoint } from "@defjs/core";
+import { ClientProvider } from "@defjs/react";
+import { UserProfile } from "./user-profile";
 
-const client = createClient(withEndpoint('https://api.example.com'))
+const client = createClient(withEndpoint("https://api.example.com"));
 
 export function App() {
   return (
     <ClientProvider client={client}>
       <UserProfile id={1} />
     </ClientProvider>
-  )
+  );
 }
 ```
 
-Read the client inside descendants and own request cleanup where the work starts:
+Read the client with `useClient()` and own request cleanup where the work starts:
 
 ```tsx
-import { useEffect, useState } from 'react'
-import { useClient } from '@defjs/react'
-import { getUser } from './api'
+import { useEffect, useState } from "react";
+import { useClient } from "@defjs/react";
+import { getUser } from "./api";
 
 export function UserProfile({ id }: { id: number }) {
-  const client = useClient()
-  const [name, setName] = useState('loading...')
+  const client = useClient();
+  const [name, setName] = useState("loading...");
 
   useEffect(() => {
-    const abort = new AbortController()
-
-    void client.execute(getUser({ path: { id } }), { signal: abort.signal }).then(([error, user]) => {
-      if (!abort.signal.aborted) setName(error ? error.message : user.name)
-    })
-
-    return () => abort.abort()
-  }, [client, id])
-
-  return <div>{name}</div>
+    const abort = new AbortController();
+
+    void getUser(client({ abort: abort.signal }), { id }).then(
+      ([error, user]) => {
+        if (abort.signal.aborted) return;
+        if (error) {
+          setName(error.message);
+          return;
+        }
+        setName(user.name);
+      },
+    );
+
+    return () => abort.abort();
+  }, [client, id]);
+
+  return <div>{name}</div>;
 }
 ```
 
-Nested providers follow normal React Context rules: descendants receive the nearest provider's exact client. Supplying a different `client` prop changes the provided value; the adapter does not invent a remount or caching policy.
-
 ## API
 
-### `<ClientProvider client: Client>`
+### `<ClientProvider client={client}>`
 
-Provides the supplied client to descendant components. `children` is optional.
+Provides the exact supplied `Client` to descendants. Nested providers follow normal React Context rules.
 
-### `useClient(): Client`
+### `useClient(overrideClient?): Client`
 
-Returns the client from the nearest `ClientProvider`. Throws if called outside a provider.
+Returns `overrideClient` when supplied, otherwise the nearest provided client. Throws only when neither source supplies one. Call it at the top level of a component or Hook — never as `explicitClient ?? useClient()`, which conditionally calls a Hook. The override does not write Context.
 
 ## Notes
 
-- The published entry is marked with `'use client'`, so React Server Component consumers treat this adapter as a client boundary.
-- Create request-specific clients at the application boundary for SSR data that contains credentials, cookies, or tenant state.
-- The owner that creates a client also owns all requests, SSE streams, and WebSocket sessions started through it. Provider unmount does not clean them up automatically.
-- Import `createClient`, `withEndpoint`, `withInterceptors`, and all other client options from `@defjs/core`.
+- `Client` is a function. `useClient()` returns that same function. Do not pass it to `useState` or a state setter: React calls a function argument as a lazy initializer or an updater and will invoke the client.
+- Create request-specific clients (SSR data with credentials, cookies, or tenant state) at the application boundary.
+- The owner that creates a client also owns its requests, SSE streams, and WebSocket sessions. Provider unmount does not clean them up.
+- Import `createClient`, `withEndpoint`, `withInterceptors`, and other client options from `@defjs/core`.
+
+## Documentation
+
+- [React API](https://defjs.lyz.cloud/api/react) · [React guide](https://defjs.lyz.cloud/docs/integrations/react)
 
 ## License
 
-MIT License.
+MIT.

package/index.d.ts

@@ -1,8 +1,11 @@
 
 import { ReactNode } from "react";
 import { Client } from "@defjs/core";
-//#region src/core.d.ts
-/** Props for {@link ClientProvider}. */
+/**
+ * Props of {@link ClientProvider}: the required `client` and optional `children`.
+ *
+ * @group react
+ */
 interface ClientProviderProps {
   /** Defjs client owned by the application. */
   client: Client;
@@ -12,30 +15,36 @@ interface ClientProviderProps {
 /**
  * Provide a Defjs client to React descendants via context.
  *
- * Does not create, cache, or dispose the client — pass an existing instance.
+ * Pass an existing client from `createClient` as `client`; descendants read it with `useClient`. The component does not create, cache, or dispose the client. A nested `ClientProvider` overrides the client for its own subtree, and a different `client` prop changes the context value for descendants.
  *
  * @param props - `client` and optional `children`.
  * @returns A context provider element.
  *
- * @example
- * ```tsx
- * <ClientProvider client={client}>
- *   <App />
- * </ClientProvider>
- * ```
+ * @group react
+ * @see {@link Client}
+ * @see {@link ClientProviderProps}
+ * @exampleFile examples/react/client-provider.tsx#example
  */
-export declare function ClientProvider({ client, children }: ClientProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<Client | null>>;
+export declare function ClientProvider({ client, children }: ClientProviderProps): React.FunctionComponentElement<React.ProviderProps<Client | null>>;
 /**
- * Read the Defjs client from the nearest {@link ClientProvider}.
+ * React Hook that returns an explicit Defjs client or the nearest {@link ClientProvider}.
+ *
+ * `useClient(overrideClient)` prefers the exact explicit client; omitted or `undefined` reads the nearest `ClientProvider`. An `Error` is thrown only when neither source supplies a client. Zero-argument `useClient()` calls remain valid.
+ *
+ * Always call `useClient(explicitClient)` at the top level of a component or custom Hook, even with an explicit client; not in an ordinary function or event callback. Do not write `explicitClient ?? useClient()`, which conditionally calls a Hook. The override does not write Context or create a provider, and the Hook still subscribes to Context.
+ *
+ * The returned value is that same function. `Client` is callable, so do not pass it to `useState` or a state setter: React calls a function argument as a lazy initializer or an updater.
  *
- * @returns The provided `Client`.
- * @throws If called outside a `ClientProvider`.
+ * @param overrideClient - Client to use before context; `undefined` uses the provider.
+ * @returns The selected client function.
+ * @throws If neither an explicit client nor a `ClientProvider` is available.
  *
  * @example
  * ```tsx
  * const client = useClient()
  * ```
+ * @group react
+ * @see {@link Client}
  */
-export declare function useClient(): Client;
-//#endregion
+export declare function useClient(overrideClient?: Client): Client;
 export type { ClientProviderProps };

package/index.js

@@ -1,40 +1,47 @@
 'use client';
 import { createContext, createElement, useContext } from "react";
-//#region src/core.ts
+// src/core.ts
 const HttpClientContext = createContext(null);
 /**
 * Provide a Defjs client to React descendants via context.
 *
-* Does not create, cache, or dispose the client — pass an existing instance.
+* Pass an existing client from `createClient` as `client`; descendants read it with `useClient`. The component does not create, cache, or dispose the client. A nested `ClientProvider` overrides the client for its own subtree, and a different `client` prop changes the context value for descendants.
 *
 * @param props - `client` and optional `children`.
 * @returns A context provider element.
 *
-* @example
-* ```tsx
-* <ClientProvider client={client}>
-*   <App />
-* </ClientProvider>
-* ```
+* @group react
+* @see {@link Client}
+* @see {@link ClientProviderProps}
+* @exampleFile examples/react/client-provider.tsx#example
 */
 function ClientProvider({ client, children }) {
 	return createElement(HttpClientContext.Provider, { value: client }, children);
 }
 /**
-* Read the Defjs client from the nearest {@link ClientProvider}.
+* React Hook that returns an explicit Defjs client or the nearest {@link ClientProvider}.
+*
+* `useClient(overrideClient)` prefers the exact explicit client; omitted or `undefined` reads the nearest `ClientProvider`. An `Error` is thrown only when neither source supplies a client. Zero-argument `useClient()` calls remain valid.
+*
+* Always call `useClient(explicitClient)` at the top level of a component or custom Hook, even with an explicit client; not in an ordinary function or event callback. Do not write `explicitClient ?? useClient()`, which conditionally calls a Hook. The override does not write Context or create a provider, and the Hook still subscribes to Context.
+*
+* The returned value is that same function. `Client` is callable, so do not pass it to `useState` or a state setter: React calls a function argument as a lazy initializer or an updater.
 *
-* @returns The provided `Client`.
-* @throws If called outside a `ClientProvider`.
+* @param overrideClient - Client to use before context; `undefined` uses the provider.
+* @returns The selected client function.
+* @throws If neither an explicit client nor a `ClientProvider` is available.
 *
 * @example
 * ```tsx
 * const client = useClient()
 * ```
+* @group react
+* @see {@link Client}
 */
-function useClient() {
-	const client = useContext(HttpClientContext);
+function useClient(overrideClient) {
+	const providedClient = useContext(HttpClientContext);
+	const client = overrideClient ?? providedClient;
 	if (!client) throw new Error("No Defjs client provided. Did you forget to wrap your app in <ClientProvider>?");
 	return client;
 }
-//#endregion
 export { ClientProvider, useClient };

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@defjs/react",
-  "version": "0.0.1-beta.1",
+  "version": "0.0.2",
+  "description": "Provide an existing Defjs client to a React tree.",
   "bugs": {
     "url": "https://github.com/defjs/defjs/issues"
   },
@@ -13,7 +14,7 @@
   "main": "./index.js",
   "types": "./index.d.ts",
   "peerDependencies": {
-    "@defjs/core": "0.4.0-beta.1",
+    "@defjs/core": "^0.5.0",
     "react": ">=18.0.0"
   },
   "module": "./index.js",