@defjs/react 0.0.1 → 0.0.2

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.5.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({ 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]);
@@ -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 `Client` to descendants. Nested providers follow normal React Context rules.
 
-### `useClient(): Client`
+### `useClient(overrideClient?): Client`
 
-```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.
+- `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`.
 
-## 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

@@ -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.
  *
+ * 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.
+ *
  * @param overrideClient - Client to use before context; `undefined` uses the provider.
- * @returns The selected `Client` instance.
+ * @returns The selected client function.
  * @throws If neither an explicit client nor a `ClientProvider` is available.
  *
  * @example

package/index.js

@@ -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.
 *
+* 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.
+*
 * @param overrideClient - Client to use before context; `undefined` uses the provider.
-* @returns The selected `Client` instance.
+* @returns The selected client function.
 * @throws If neither an explicit client nor a `ClientProvider` is available.
 *
 * @example

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defjs/react",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "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.5.0",
     "react": ">=18.0.0"
   },
   "module": "./index.js",