@defjs/vue 0.0.1-beta.0 → 0.0.2

package/README.md

@@ -1,8 +1,8 @@
 # @defjs/vue
 
-Thin Vue 3 adapter for `@defjs/core`. It provides an existing Defjs client through Vue injection.
+Thin Vue 3 plugin for `@defjs/core`: it provides an application-owned client through Vue injection. It adds no transport behavior, state management, retries, or Nuxt module, and never creates, replaces, or disposes a client.
 
-Supports Vue 3+.
+Keeping SDK definitions in their own package means the SDK needs no Vue dependency. Requires Vue 3 or later.
 
 ## Install
 
@@ -10,56 +10,55 @@ Supports Vue 3+.
 bun add @defjs/core @defjs/vue vue
 ```
 
-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.
+The package is ESM and requires `@defjs/core` as a peer in the `^0.5.0` range.
 
-## What this package does
-
-`createClientPlugin(client)` creates a Vue plugin that provides the exact `Client` instance supplied by the application. `injectClient()` reads the nearest provided instance. `HTTP_CLIENT` remains public for native subtree overrides.
-
-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 transport behavior, state management, retries, or a Nuxt module.
-
-## Quick Start
-
-Create and own the client at the application entry point:
+## Quick start
 
 ```ts
-// main.ts
-import { createClient, withEndpoint } from '@defjs/core'
-import { createClientPlugin } from '@defjs/vue'
-import { createApp } from 'vue'
-import App from './App.vue'
+// main.ts — application entry point
+import { createClient, withEndpoint } from "@defjs/core";
+import { createClientPlugin } from "@defjs/vue";
+import { createApp } from "vue";
+import App from "./App.vue";
 
-const client = createClient(withEndpoint('https://api.example.com'))
-const app = createApp(App)
+const client = createClient(withEndpoint("https://api.example.com"));
+const app = createApp(App);
 
-app.use(createClientPlugin(client))
-app.mount('#app')
+app.use(createClientPlugin(client));
+app.mount("#app");
 ```
 
-Use the injected client inside a component or composable and own cleanup where the work starts:
+Read the client with `injectClient()` and own cleanup in the watcher:
 
 ```vue
 <script setup lang="ts">
-import { ref, watch } from 'vue'
-import { injectClient } from '@defjs/vue'
-import { getUser } from './api'
+import { ref, watch } from "vue";
+import { injectClient } from "@defjs/vue";
+import { getUser } from "./api";
 
-const props = defineProps<{ id: number }>()
-const client = injectClient()
-const name = ref('')
+const props = defineProps<{ id: number }>();
+const client = injectClient();
+const name = ref("");
 
 watch(
   () => props.id,
   (id, _previousId, onCleanup) => {
-    const abort = new AbortController()
-    onCleanup(() => abort.abort())
-
-    void client.execute(getUser({ path: { id } }), { signal: abort.signal }).then(([error, user]) => {
-      if (!abort.signal.aborted) name.value = error ? error.message : user.name
-    })
+    const abort = new AbortController();
+    onCleanup(() => abort.abort());
+
+    void getUser(client({ abort: abort.signal }), { id }).then(
+      ([error, user]) => {
+        if (abort.signal.aborted) return;
+        if (error) {
+          name.value = error.message;
+          return;
+        }
+        name.value = user.name;
+      },
+    );
   },
   { immediate: true },
-)
+);
 </script>
 
 <template>
@@ -67,54 +66,47 @@ watch(
 </template>
 ```
 
-Configure interceptors in core before installing the plugin:
+## API
 
-```ts
-import { createClient, createHttpInterceptor, withEndpoint, withInterceptors } from '@defjs/core'
-import { createClientPlugin } from '@defjs/vue'
+### `createClientPlugin(client): Plugin`
 
-const auth = createHttpInterceptor((request, next) => {
-  const headers = new Headers(request.headers)
-  headers.set('Authorization', `Bearer ${getAccessToken()}`)
-  return next({ ...request, headers })
-})
+Creates a Vue plugin that provides the supplied client as `HTTP_CLIENT`.
 
-const client = createClient(withEndpoint('https://api.example.com'), withInterceptors(auth))
-app.use(createClientPlugin(client))
-```
+### `injectClient(key?): Client`
 
-For a subtree override, use Vue's native provider with the public key:
+Returns the nearest client for `key`, defaulting to `HTTP_CLIENT`. Call it in a valid injection context: synchronous `setup()` or `app.runWithContext()` (Vue 3.3+). Throws without an active context or a client for the key; a missing custom key never falls back to `HTTP_CLIENT`.
 
-```ts
-import { createClient, withEndpoint } from '@defjs/core'
-import { HTTP_CLIENT } from '@defjs/vue'
-import { provide } from 'vue'
+### `HTTP_CLIENT`
 
-provide(HTTP_CLIENT, createClient(withEndpoint('https://preview.example.com')))
-```
+Public `InjectionKey<Client>` for native subtree overrides:
 
-Descendants receive that exact client; siblings outside the subtree continue to receive the app-level client.
-
-## API
-
-### `createClientPlugin(client: Client): Plugin`
+```ts
+provide(HTTP_CLIENT, createClient(withEndpoint("https://preview.example.com")));
+```
 
-Creates a Vue plugin that provides the supplied client instance.
+Descendants receive that client; siblings outside the subtree keep the app-level one.
 
-### `injectClient(): Client`
+Interceptors and every other client option belong to `@defjs/core` and are configured before the plugin is installed:
 
-Returns the client from the nearest Vue provider. Throws if no client was provided.
+```ts
+const client = createClient(
+  withEndpoint("https://api.example.com"),
+  withInterceptors(auth),
+);
+app.use(createClientPlugin(client));
+```
 
-### `HTTP_CLIENT: InjectionKey<Client>`
+## Notes
 
-Public injection key for native subtree providers.
+- `Client` is a function. `injectClient()` returns that same function. Pass it straight to `createClientPlugin` or `provide`. Do not pass it to `watch` or `computed` as the source: Vue calls a function source. Do not wrap it in `ref` or `reactive`; the plugin stores the function as-is.
+- 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. App unmount does not clean them up.
+- Import `createClient`, `withEndpoint`, `withInterceptors`, and other client options from `@defjs/core`.
 
-## Notes
+## Documentation
 
-- 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. App unmount does not clean them up automatically.
-- Import `createClient`, `withEndpoint`, `withInterceptors`, and all other client options from `@defjs/core`.
+- [Vue API](https://defjs.lyz.cloud/api/vue) · [Vue guide](https://defjs.lyz.cloud/docs/integrations/vue)
 
 ## License
 
-MIT License.
+MIT.

package/index.d.ts

@@ -1,36 +1,50 @@
 import { InjectionKey, Plugin } from "vue";
 import { Client } from "@defjs/core";
-//#region src/core.d.ts
 /**
  * Vue injection key for the Defjs {@link Client} provided by {@link createClientPlugin}.
  *
- * Prefer {@link injectClient} over calling `inject(HTTP_CLIENT)` directly.
+ * Prefer {@link injectClient} over calling `inject(HTTP_CLIENT)` directly. `inject(HTTP_CLIENT)` returns `undefined` when nothing was provided. Override a subtree with `provide(HTTP_CLIENT, childClient)`.
+ *
+ * @group vue
+ * @see {@link Client}
+ * @see {@link injectClient}
  */
 export declare const HTTP_CLIENT: InjectionKey<Client>;
 /**
  * Create a Vue plugin that provides an existing Defjs client via {@link HTTP_CLIENT}.
  *
- * Does not create, cache, or dispose the client — pass an instance from `createClient`.
+ * Does not create, cache, or dispose the client — pass the function from `createClient`. Installing it calls `app.provide(HTTP_CLIENT, client)`, so components read the client with `injectClient()`. The client is stored as that function: it is not wrapped in `ref`, `reactive`, or `markRaw`.
  *
- * @param client - The Client instance to provide to the app.
+ * @param client - The client function to provide to the app.
  * @returns A Vue `Plugin` for `app.use(...)`.
  *
- * @example
- * ```ts
- * app.use(createClientPlugin(client))
- * ```
+ * @group vue
+ * @see {@link Client}
+ * @exampleFile examples/api/create-client-plugin.ts#example
  */
 export declare function createClientPlugin(client: Client): Plugin;
 /**
- * Inject the Defjs client provided by {@link createClientPlugin}.
+ * Vue composable that injects the Defjs client for a key, defaulting to {@link HTTP_CLIENT}.
+ *
+ * `injectClient(key)` reads the nearest provider for that key; omitted or `undefined` uses `HTTP_CLIENT`. Call in a valid Vue injection context: synchronous `setup()`, compiler-restored `<script setup>` after top-level `await`, or a synchronous `app.runWithContext()` callback (Vue 3.3+). `app.runWithContext()` supplies only synchronous app-level context, not subtree overrides or context across ordinary `await`.
+ *
+ * For a custom `InjectionKey<Client>`, use `app.provide(key, client)` or an ancestor’s `provide(key, client)`. Share the same `Symbol` object; matching descriptions do not make keys equal. `createClientPlugin(client)` still takes only the client and provides `HTTP_CLIENT`.
+ *
+ * It returns the exact client function provided for the selected key, and throws an `Error` without an active injection context or a client for the selected key. Installing the plugin alone does not establish an injection context.
+ *
+ * `Client` is callable. Pass it to `provide` as-is. Do not pass it to `watch` or `computed` as the source: Vue calls a function source. Do not wrap it in `ref` or `reactive`.
  *
- * @returns The injected `Client` instance.
- * @throws If no client was provided (plugin not installed).
+ * @param key - Injection key; use the same object with `app.provide` or `provide`.
+ * Defaults to `HTTP_CLIENT`, as provided by {@link createClientPlugin}.
+ * @returns The injected client function.
+ * @throws If called outside a Vue injection context or no client was provided for
+ * the requested key. A missing custom key does not fall back to `HTTP_CLIENT`.
  *
  * @example
  * ```ts
  * const client = injectClient()
  * ```
+ * @group vue
+ * @see {@link Client}
  */
-export declare function injectClient(): Client;
-//#endregion
+export declare function injectClient(key?: InjectionKey<Client>): Client;

package/index.js

@@ -1,23 +1,26 @@
 import { inject } from "vue";
-//#region src/core.ts
+// src/core.ts
 /**
 * Vue injection key for the Defjs {@link Client} provided by {@link createClientPlugin}.
 *
-* Prefer {@link injectClient} over calling `inject(HTTP_CLIENT)` directly.
+* Prefer {@link injectClient} over calling `inject(HTTP_CLIENT)` directly. `inject(HTTP_CLIENT)` returns `undefined` when nothing was provided. Override a subtree with `provide(HTTP_CLIENT, childClient)`.
+*
+* @group vue
+* @see {@link Client}
+* @see {@link injectClient}
 */
 const HTTP_CLIENT = Symbol("HTTP_CLIENT");
 /**
 * Create a Vue plugin that provides an existing Defjs client via {@link HTTP_CLIENT}.
 *
-* Does not create, cache, or dispose the client — pass an instance from `createClient`.
+* Does not create, cache, or dispose the client — pass the function from `createClient`. Installing it calls `app.provide(HTTP_CLIENT, client)`, so components read the client with `injectClient()`. The client is stored as that function: it is not wrapped in `ref`, `reactive`, or `markRaw`.
 *
-* @param client - The Client instance to provide to the app.
+* @param client - The client function to provide to the app.
 * @returns A Vue `Plugin` for `app.use(...)`.
 *
-* @example
-* ```ts
-* app.use(createClientPlugin(client))
-* ```
+* @group vue
+* @see {@link Client}
+* @exampleFile examples/api/create-client-plugin.ts#example
 */
 function createClientPlugin(client) {
 	return { install(app) {
@@ -25,20 +28,32 @@ function createClientPlugin(client) {
 	} };
 }
 /**
-* Inject the Defjs client provided by {@link createClientPlugin}.
+* Vue composable that injects the Defjs client for a key, defaulting to {@link HTTP_CLIENT}.
+*
+* `injectClient(key)` reads the nearest provider for that key; omitted or `undefined` uses `HTTP_CLIENT`. Call in a valid Vue injection context: synchronous `setup()`, compiler-restored `<script setup>` after top-level `await`, or a synchronous `app.runWithContext()` callback (Vue 3.3+). `app.runWithContext()` supplies only synchronous app-level context, not subtree overrides or context across ordinary `await`.
+*
+* For a custom `InjectionKey<Client>`, use `app.provide(key, client)` or an ancestor’s `provide(key, client)`. Share the same `Symbol` object; matching descriptions do not make keys equal. `createClientPlugin(client)` still takes only the client and provides `HTTP_CLIENT`.
+*
+* It returns the exact client function provided for the selected key, and throws an `Error` without an active injection context or a client for the selected key. Installing the plugin alone does not establish an injection context.
+*
+* `Client` is callable. Pass it to `provide` as-is. Do not pass it to `watch` or `computed` as the source: Vue calls a function source. Do not wrap it in `ref` or `reactive`.
 *
-* @returns The injected `Client` instance.
-* @throws If no client was provided (plugin not installed).
+* @param key - Injection key; use the same object with `app.provide` or `provide`.
+* Defaults to `HTTP_CLIENT`, as provided by {@link createClientPlugin}.
+* @returns The injected client function.
+* @throws If called outside a Vue injection context or no client was provided for
+* the requested key. A missing custom key does not fall back to `HTTP_CLIENT`.
 *
 * @example
 * ```ts
 * const client = injectClient()
 * ```
+* @group vue
+* @see {@link Client}
 */
-function injectClient() {
-	const client = inject(HTTP_CLIENT);
-	if (!client) throw new Error("No Defjs client provided. Did you forget to call app.use(createClientPlugin(client))?");
+function injectClient(key = HTTP_CLIENT) {
+	const client = inject(key);
+	if (!client) throw new Error(key === HTTP_CLIENT ? "No Defjs client available. Call injectClient() in a Vue injection context (such as synchronous setup() or app.runWithContext()) and provide a client with app.use(createClientPlugin(client)) or provide(HTTP_CLIENT, client)." : "No Defjs client available for the requested injection key. Call injectClient(key) in a Vue injection context and provide a client with app.provide(key, client) or provide(key, client). Use the same key object when providing and injecting.");
 	return client;
 }
-//#endregion
 export { HTTP_CLIENT, createClientPlugin, injectClient };

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@defjs/vue",
-  "version": "0.0.1-beta.0",
+  "version": "0.0.2",
+  "description": "Provide an existing Defjs client to a Vue application.",
   "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.5.0",
     "vue": ">=3.0.0"
   },
   "module": "./index.js",