@defjs/react 0.0.1 → 0.0.3

package/README.md

@@ -1,12 +1,8 @@
 # @defjs/react
 
-Thin React plugin 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.
 
-Keep reusable SDK definitions in their own package or module. A React application configures the client, provides it to components, and executes those definitions through `useClient()`. The SDK does not need a React dependency or a component-owned client.
-
-This plugin is optional: import a fixed application-owned client, pass a `Client` explicitly, use Context for tree-level defaults and overrides, or choose your own organization. SDK definitions do not require this plugin. Share an instance only when its captured configuration and state are safe to share; request-specific identity or credentials belong to the appropriate request boundary.
-
-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
 
@@ -14,20 +10,12 @@ 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.
-
-## 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 plugin 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
+The package is ESM and requires `@defjs/core` as a peer in the `^0.6.0` range.
 
-Define the SDK's requests in a shared module, or import them from your published SDK:
+## Quick start
 
 ```tsx
-// api.ts
+// api.ts — reusable definition
 import { defineRequest, struct } from "@defjs/core";
 
 export const getUser = defineRequest({
@@ -39,8 +27,6 @@ export const getUser = defineRequest({
 });
 ```
 
-Create and own the client at the application boundary, then provide it:
-
 ```tsx
 // app.tsx
 import { createClient, withEndpoint } from "@defjs/core";
@@ -58,7 +44,7 @@ export function App() {
 }
 ```
 
-Read the client inside descendants and own request cleanup where the work starts. Best practice: name the command, pass that name to `execute`, and return before reading the user when `error` is set. Abort still belongs to the effect:
+Read the client with `useClient()` and own request cleanup where the work starts:
 
 ```tsx
 import { useEffect, useState } from "react";
@@ -72,17 +58,16 @@ export function UserProfile({ id }: { id: number }) {
   useEffect(() => {
     const abort = new AbortController();
 
-    const command = getUser({ id });
-    void client
-      .execute(command, { signal: abort.signal })
-      .then(([error, user]) => {
+    void getUser(client({ signal: 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]);
@@ -91,31 +76,27 @@ export function UserProfile({ id }: { id: number }) {
 }
 ```
 
-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 plugin 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 `DerivableClient` to descendants. Nested providers follow normal React Context rules.
 
-### `useClient(): Client`
+### `useClient(overrideClient?): DerivableClient`
 
-```ts
-function useClient(overrideClient?: Client): Client;
-```
+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.
 
-Returns the exact `overrideClient` when supplied; omitted or `undefined` reads the nearest `ClientProvider`. Throws an `Error` only when neither source supplies a client. Zero-argument calls remain valid.
+## Notes
 
-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.
+- `useClient()` returns the `DerivableClient` that was supplied, a function. Call it with request options where the operation runs to derive a `Client` value. 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 it. A derived `Client` value is not accepted by `ClientProvider` or `useClient`.
+- 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`.
 
-## Notes
+## Documentation
 
-- The published entry is marked with `'use client'`, so React Server Component consumers treat this plugin 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`.
+- [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,31 +1,31 @@
 
 import { ReactNode } from "react";
-import { Client } from "@defjs/core";
+import { DerivableClient } from "@defjs/core";
 /**
  * Props of {@link ClientProvider}: the required `client` and optional `children`.
  *
  * @group react
  */
 interface ClientProviderProps {
-  /** Defjs client owned by the application. */
-  client: Client;
+  /** Derivable client returned by `createClient`, owned by the application. */
+  client: DerivableClient;
   /** React tree that can call {@link useClient}. */
   children?: ReactNode;
 }
 /**
  * Provide a Defjs client to React descendants via context.
  *
- * 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.
+ * Pass the client returned by `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.
  *
  * @group react
- * @see {@link Client}
+ * @see {@link DerivableClient}
  * @see {@link ClientProviderProps}
  * @exampleFile examples/react/client-provider.tsx#example
  */
-export declare function ClientProvider({ client, children }: ClientProviderProps): React.FunctionComponentElement<React.ProviderProps<Client | null>>;
+export declare function ClientProvider({ client, children }: ClientProviderProps): React.FunctionComponentElement<React.ProviderProps<DerivableClient | null>>;
 /**
  * React Hook that returns an explicit Defjs client or the nearest {@link ClientProvider}.
  *
@@ -33,8 +33,10 @@ export declare function ClientProvider({ client, children }: ClientProviderProps
  *
  * 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.
  *
- * @param overrideClient - Client to use before context; `undefined` uses the provider.
- * @returns The selected `Client` instance.
+ * The returned value is the exact `DerivableClient` that was supplied. Call it with request options at the call site to derive a `Client` value for one call: `getUser(client({ signal }), input)`. It is a function, so do not pass it to `useState` or a state setter: React calls a function argument as a lazy initializer or an updater. The provider holds only a root client; a derived `Client` value is not accepted, so create it where the operation is called.
+ *
+ * @param overrideClient - Derivable client to use before context; `undefined` uses the provider.
+ * @returns The selected derivable client.
  * @throws If neither an explicit client nor a `ClientProvider` is available.
  *
  * @example
@@ -42,7 +44,7 @@ export declare function ClientProvider({ client, children }: ClientProviderProps
  * const client = useClient()
  * ```
  * @group react
- * @see {@link Client}
+ * @see {@link DerivableClient}
  */
-export declare function useClient(overrideClient?: Client): Client;
+export declare function useClient(overrideClient?: DerivableClient): DerivableClient;
 export type { ClientProviderProps };

package/index.js

@@ -5,13 +5,13 @@ const HttpClientContext = createContext(null);
 /**
 * Provide a Defjs client to React descendants via context.
 *
-* 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.
+* Pass the client returned by `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.
 *
 * @group react
-* @see {@link Client}
+* @see {@link DerivableClient}
 * @see {@link ClientProviderProps}
 * @exampleFile examples/react/client-provider.tsx#example
 */
@@ -25,8 +25,10 @@ function ClientProvider({ client, children }) {
 *
 * 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.
 *
-* @param overrideClient - Client to use before context; `undefined` uses the provider.
-* @returns The selected `Client` instance.
+* The returned value is the exact `DerivableClient` that was supplied. Call it with request options at the call site to derive a `Client` value for one call: `getUser(client({ signal }), input)`. It is a function, so do not pass it to `useState` or a state setter: React calls a function argument as a lazy initializer or an updater. The provider holds only a root client; a derived `Client` value is not accepted, so create it where the operation is called.
+*
+* @param overrideClient - Derivable client to use before context; `undefined` uses the provider.
+* @returns The selected derivable client.
 * @throws If neither an explicit client nor a `ClientProvider` is available.
 *
 * @example
@@ -34,7 +36,7 @@ function ClientProvider({ client, children }) {
 * const client = useClient()
 * ```
 * @group react
-* @see {@link Client}
+* @see {@link DerivableClient}
 */
 function useClient(overrideClient) {
 	const providedClient = useContext(HttpClientContext);

package/package.json

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