@defjs/vue 0.0.1 → 0.0.3

package/README.md

@@ -1,12 +1,8 @@
 # @defjs/vue
 
-Thin Vue 3 plugin 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.
 
-Keep reusable SDK definitions in their own package or module. A Vue application configures the client, provides it through this plugin, and executes imported definitions. The SDK does not need a Vue dependency or an application-owned client.
-
-This plugin is optional: import a fixed application-owned client, pass a `Client` explicitly, use Vue injection 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 Vue 3+.
+Keeping SDK definitions in their own package means the SDK needs no Vue dependency. Requires Vue 3 or later.
 
 ## Install
 
@@ -14,20 +10,12 @@ 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.
-
-## 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 plugin 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.
+The package is ESM and requires `@defjs/core` as a peer in the `^0.6.0` range.
 
-## Quick Start
-
-Create and own the client at the application entry point:
+## Quick start
 
 ```ts
-// main.ts
+// main.ts — application entry point
 import { createClient, withEndpoint } from "@defjs/core";
 import { createClientPlugin } from "@defjs/vue";
 import { createApp } from "vue";
@@ -40,7 +28,7 @@ app.use(createClientPlugin(client));
 app.mount("#app");
 ```
 
-Import `getUser` from your SDK or a local `api.ts` module that exports a `defineRequest(...)` endpoint. Use the injected client inside a component or composable and own 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 watcher:
+Read the client with `injectClient()` and own cleanup in the watcher:
 
 ```vue
 <script setup lang="ts">
@@ -58,17 +46,16 @@ watch(
     const abort = new AbortController();
     onCleanup(() => abort.abort());
 
-    const command = getUser({ id });
-    void client
-      .execute(command, { signal: abort.signal })
-      .then(([error, user]) => {
+    void getUser(client({ signal: abort.signal }), { id }).then(
+      ([error, user]) => {
         if (abort.signal.aborted) return;
         if (error) {
           name.value = error.message;
           return;
         }
         name.value = user.name;
-      });
+      },
+    );
   },
   { immediate: true },
 );
@@ -79,72 +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?): DerivableClient`
 
-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`
 
+Public `InjectionKey<DerivableClient>` for native subtree overrides:
+
+```ts
 provide(HTTP_CLIENT, createClient(withEndpoint("https://preview.example.com")));
 ```
 
-Descendants receive that exact client; siblings outside the subtree continue to receive the app-level client. The providing component itself still reads from its ancestors.
-
-## API
-
-### `createClientPlugin(client: Client): Plugin`
+Descendants receive that client; siblings outside the subtree keep the app-level one.
 
-Creates a Vue plugin that provides the supplied client instance.
-
-### `injectClient(): Client`
+Interceptors and every other client option belong to `@defjs/core` and are configured before the plugin is installed:
 
 ```ts
-function injectClient(key?: InjectionKey<Client>): Client;
+const client = createClient(
+  withEndpoint("https://api.example.com"),
+  withInterceptors(auth),
+);
+app.use(createClientPlugin(client));
 ```
 
-Returns the nearest client provided for `key`; omitted or `undefined` uses `HTTP_CLIENT`. For a custom `InjectionKey<Client>`, use `app.provide(key, client)` or an ancestor's `provide(key, client)`. Both sides must share the same `Symbol` object: matching descriptions do not make keys equal. `createClientPlugin(client)` still takes only the client and provides `HTTP_CLIENT`.
-
-Call in a valid Vue injection context, such as synchronous `setup()` or `app.runWithContext()` (Vue 3.3+). The latter is synchronous app-level context only: no component subtree overrides and no context across ordinary `await`. Compiler-restored contexts after top-level `await` in `<script setup>` remain valid.
-
-Throws an `Error` without an active injection context or a client for the selected key; a missing custom key never falls back to `HTTP_CLIENT`. Installing the plugin alone does not establish an injection context.
-
-An application function that only retrieves a client may use `explicitClient ?? injectClient()`: only the fallback branch needs injection context. Other lifecycle APIs in that composable retain their own context requirements. Read the client before async work and reuse the object.
-
-### `HTTP_CLIENT: InjectionKey<Client>`
+## Notes
 
-Public injection key for native subtree providers.
+- `injectClient()` returns the `DerivableClient` that was provided, a function. Call it with request options where the operation runs to derive a `Client` value. 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 it as-is. A derived `Client` value is not accepted.
+- 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,40 +1,42 @@
 import { InjectionKey, Plugin } from "vue";
-import { Client } from "@defjs/core";
+import { DerivableClient } from "@defjs/core";
 /**
- * Vue injection key for the Defjs {@link Client} provided by {@link createClientPlugin}.
+ * Vue injection key for the Defjs {@link DerivableClient} provided by {@link createClientPlugin}.
  *
  * 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 DerivableClient}
  * @see {@link injectClient}
  */
-export declare const HTTP_CLIENT: InjectionKey<Client>;
+export declare const HTTP_CLIENT: InjectionKey<DerivableClient>;
 /**
  * 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`. Installing it calls `app.provide(HTTP_CLIENT, client)`, so components read the client with `injectClient()`.
+ * Does not create, cache, or dispose the client — pass the client returned by `createClient`. Installing it calls `app.provide(HTTP_CLIENT, client)`, so components read the client with `injectClient()`. The client is stored as given: it is not wrapped in `ref`, `reactive`, or `markRaw`.
  *
- * @param client - The Client instance to provide to the app.
+ * @param client - The client returned by `createClient` to provide to the app.
  * @returns A Vue `Plugin` for `app.use(...)`.
  *
  * @group vue
- * @see {@link Client}
+ * @see {@link DerivableClient}
  * @exampleFile examples/api/create-client-plugin.ts#example
  */
-export declare function createClientPlugin(client: Client): Plugin;
+export declare function createClientPlugin(client: DerivableClient): Plugin;
 /**
  * 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`.
+ * For a custom `InjectionKey<DerivableClient>`, 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 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.
+ * It returns the exact client value 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.
+ *
+ * The injected `DerivableClient` is a function. Call it with request options at the call site to derive a `Client` value for one call: `getUser(client({ signal }), input)`. 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 provider holds only a root client; a derived `Client` value is not accepted, so create it where the operation is called.
  *
  * @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` instance.
+ * @returns The injected derivable client.
  * @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`.
  *
@@ -43,6 +45,6 @@ export declare function createClientPlugin(client: Client): Plugin;
  * const client = injectClient()
  * ```
  * @group vue
- * @see {@link Client}
+ * @see {@link DerivableClient}
  */
-export declare function injectClient(key?: InjectionKey<Client>): Client;
+export declare function injectClient(key?: InjectionKey<DerivableClient>): DerivableClient;

package/index.js

@@ -1,25 +1,25 @@
 import { inject } from "vue";
 // src/core.ts
 /**
-* Vue injection key for the Defjs {@link Client} provided by {@link createClientPlugin}.
+* Vue injection key for the Defjs {@link DerivableClient} provided by {@link createClientPlugin}.
 *
 * 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 DerivableClient}
 * @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`. Installing it calls `app.provide(HTTP_CLIENT, client)`, so components read the client with `injectClient()`.
+* Does not create, cache, or dispose the client — pass the client returned by `createClient`. Installing it calls `app.provide(HTTP_CLIENT, client)`, so components read the client with `injectClient()`. The client is stored as given: it is not wrapped in `ref`, `reactive`, or `markRaw`.
 *
-* @param client - The Client instance to provide to the app.
+* @param client - The client returned by `createClient` to provide to the app.
 * @returns A Vue `Plugin` for `app.use(...)`.
 *
 * @group vue
-* @see {@link Client}
+* @see {@link DerivableClient}
 * @exampleFile examples/api/create-client-plugin.ts#example
 */
 function createClientPlugin(client) {
@@ -32,13 +32,15 @@ function createClientPlugin(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`.
+* For a custom `InjectionKey<DerivableClient>`, 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 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.
+* It returns the exact client value 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.
+*
+* The injected `DerivableClient` is a function. Call it with request options at the call site to derive a `Client` value for one call: `getUser(client({ signal }), input)`. 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 provider holds only a root client; a derived `Client` value is not accepted, so create it where the operation is called.
 *
 * @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` instance.
+* @returns The injected derivable client.
 * @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`.
 *
@@ -47,7 +49,7 @@ function createClientPlugin(client) {
 * const client = injectClient()
 * ```
 * @group vue
-* @see {@link Client}
+* @see {@link DerivableClient}
 */
 function injectClient(key = HTTP_CLIENT) {
 	const client = inject(key);

package/package.json

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