@defjs/react 0.0.1-beta.0 → 0.0.1

package/README.md

@@ -1,6 +1,10 @@
 # @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 existing Defjs client through React Context.
+
+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+.
 
@@ -16,76 +20,78 @@ The package is ESM and requires `@defjs/core` as a peer in the `^0.4.0` range. I
 
 `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.
+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
 
-Define requests in a shared module:
+Define the SDK's requests in a shared module, or import them from your published SDK:
 
 ```tsx
 // api.ts
-import { defineRequest, struct } from '@defjs/core'
+import { defineRequest, struct } from "@defjs/core";
 
 export const getUser = defineRequest({
-  method: 'GET',
-  path: '/users/:id',
-  input: struct.request({
-    path: struct.object({ id: struct.number() }),
-  }),
-  output: [
-    {
-      status: 200,
-      body: struct.object({ id: struct.number(), name: struct.string() }),
-    },
-  ],
-})
+  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 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:
 
 ```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();
+
+    const command = getUser({ id });
+    void client
+      .execute(command, { signal: abort.signal })
+      .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.
+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
 
@@ -95,11 +101,17 @@ Provides the supplied client to descendant components. `children` is optional.
 
 ### `useClient(): Client`
 
-Returns the client from the nearest `ClientProvider`. Throws if called outside a provider.
+```ts
+function useClient(overrideClient?: Client): Client;
+```
+
+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.
+
+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.
 
 ## Notes
 
-- The published entry is marked with `'use client'`, so React Server Component consumers treat this adapter as a client boundary.
+- 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`.

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,34 @@ 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.
  *
- * @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` instance.
+ * @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,45 @@
 '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.
 *
-* @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` instance.
+* @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.0",
+  "version": "0.0.1",
+  "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.0",
+    "@defjs/core": "^0.4.0",
     "react": ">=18.0.0"
   },
   "module": "./index.js",