@defjs/react 0.0.2 → 0.0.4

package/README.md

@@ -10,7 +10,7 @@ Keeping SDK definitions in their own package means the SDK needs no React depend
 bun add @defjs/core @defjs/react react
 ```
 
-The package is ESM and requires `@defjs/core` as a peer in the `^0.5.0` range.
+The package is ESM and requires `@defjs/core` as a peer in the `^0.7.0` range.
 
 ## Quick start
 
@@ -18,12 +18,12 @@ The package is ESM and requires `@defjs/core` as a peer in the `^0.5.0` range.
 // api.ts — reusable definition
 import { defineRequest, struct } from "@defjs/core";
 
-export const getUser = defineRequest({
+export const getOrder = defineRequest({
   method: "GET",
-  path: "/users/:id",
+  path: "/orders/:id",
   input: struct.object({ id: struct.number() }),
   builder: (input) => ({ path: input }),
-  output: struct.object({ id: struct.number(), name: struct.string() }),
+  output: struct.object({ id: struct.number(), status: struct.string() }),
 });
 ```
 
@@ -31,14 +31,14 @@ export const getUser = defineRequest({
 // app.tsx
 import { createClient, withEndpoint } from "@defjs/core";
 import { ClientProvider } from "@defjs/react";
-import { UserProfile } from "./user-profile";
+import { OrderProfile } from "./order-profile";
 
 const client = createClient(withEndpoint("https://api.example.com"));
 
 export function App() {
   return (
     <ClientProvider client={client}>
-      <UserProfile id={1} />
+      <OrderProfile id={1} />
     </ClientProvider>
   );
 }
@@ -49,23 +49,23 @@ 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 { getOrder } from "./api";
 
-export function UserProfile({ id }: { id: number }) {
+export function OrderProfile({ id }: { id: number }) {
   const client = useClient();
   const [name, setName] = useState("loading...");
 
   useEffect(() => {
     const abort = new AbortController();
 
-    void getUser(client({ abort: abort.signal }), { id }).then(
-      ([error, user]) => {
+    void getOrder(client({ signal: abort.signal }), { id }).then(
+      ([error, order]) => {
         if (abort.signal.aborted) return;
         if (error) {
           setName(error.message);
           return;
         }
-        setName(user.name);
+        setName(order.status);
       },
     );
 
@@ -80,16 +80,16 @@ export function UserProfile({ id }: { id: number }) {
 
 ### `<ClientProvider client={client}>`
 
-Provides the exact supplied `Client` to descendants. Nested providers follow normal React Context rules.
+Provides the exact supplied `DerivableClient` to descendants. Nested providers follow normal React Context rules.
 
-### `useClient(overrideClient?): Client`
+### `useClient(overrideClient?): DerivableClient`
 
 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
 
-- `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.
+- `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 with per-request 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`.
 

package/index.d.ts

@@ -1,31 +1,31 @@
 
-import { ReactNode } from "react";
-import { Client } from "@defjs/core";
+import { ReactElement, ReactNode } from "react";
+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): ReactElement;
 /**
  * React Hook that returns an explicit Defjs client or the nearest {@link ClientProvider}.
  *
@@ -33,10 +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.
+ * 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: `getOrder(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 - Client to use before context; `undefined` uses the provider.
- * @returns The selected client function.
+ * @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
@@ -44,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,10 +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.
+* 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: `getOrder(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 - Client to use before context; `undefined` uses the provider.
-* @returns The selected client function.
+* @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
@@ -36,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.2",
+  "version": "0.0.4",
   "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.5.0",
+    "@defjs/core": "^0.7.0",
     "react": ">=18.0.0"
   },
   "module": "./index.js",