@defjs/react 0.0.1-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MunMunMiao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# @defjs/react
+
+Thin React adapter for `@defjs/core`. It provides an existing Defjs client through React Context.
+
+Supports React 18+.
+
+## Install
+
+```sh
+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 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:
+
+```tsx
+// api.ts
+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() }),
+    },
+  ],
+})
+```
+
+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'
+
+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:
+
+```tsx
+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...')
+
+  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>
+}
+```
+
+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>`
+
+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.
+
+## 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`.
+
+## License
+
+MIT License.

package/index.d.ts

@@ -0,0 +1,41 @@
+
+import { ReactNode } from "react";
+import { Client } from "@defjs/core";
+//#region src/core.d.ts
+/** Props for {@link ClientProvider}. */
+interface ClientProviderProps {
+  /** Defjs client owned by the application. */
+  client: Client;
+  /** React tree that can call {@link useClient}. */
+  children?: ReactNode;
+}
+/**
+ * Provide a Defjs client to React descendants via context.
+ *
+ * Does not create, cache, or dispose the client — pass an existing instance.
+ *
+ * @param props - `client` and optional `children`.
+ * @returns A context provider element.
+ *
+ * @example
+ * ```tsx
+ * <ClientProvider client={client}>
+ *   <App />
+ * </ClientProvider>
+ * ```
+ */
+export declare function ClientProvider({ client, children }: ClientProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<Client | null>>;
+/**
+ * Read the Defjs client from the nearest {@link ClientProvider}.
+ *
+ * @returns The provided `Client`.
+ * @throws If called outside a `ClientProvider`.
+ *
+ * @example
+ * ```tsx
+ * const client = useClient()
+ * ```
+ */
+export declare function useClient(): Client;
+//#endregion
+export type { ClientProviderProps };

package/index.js

@@ -0,0 +1,40 @@
+'use client';
+import { createContext, createElement, useContext } from "react";
+//#region 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.
+*
+* @param props - `client` and optional `children`.
+* @returns A context provider element.
+*
+* @example
+* ```tsx
+* <ClientProvider client={client}>
+*   <App />
+* </ClientProvider>
+* ```
+*/
+function ClientProvider({ client, children }) {
+	return createElement(HttpClientContext.Provider, { value: client }, children);
+}
+/**
+* Read the Defjs client from the nearest {@link ClientProvider}.
+*
+* @returns The provided `Client`.
+* @throws If called outside a `ClientProvider`.
+*
+* @example
+* ```tsx
+* const client = useClient()
+* ```
+*/
+function useClient() {
+	const client = useContext(HttpClientContext);
+	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

@@ -0,0 +1,28 @@
+{
+  "name": "@defjs/react",
+  "version": "0.0.1-beta.0",
+  "bugs": {
+    "url": "https://github.com/defjs/defjs/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/defjs/defjs.git"
+  },
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "peerDependencies": {
+    "@defjs/core": "0.4.0-beta.0",
+    "react": ">=18.0.0"
+  },
+  "module": "./index.js",
+  "typings": "./index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  }
+}