@defjs/vue 0.0.1-beta.0 → 0.0.1

package/README.md

@@ -1,6 +1,10 @@
 # @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 existing Defjs client through Vue injection.
+
+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+.
 
@@ -16,7 +20,7 @@ The package is ESM and requires `@defjs/core` as a peer in the `^0.4.0` range. I
 
 `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.
+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.
 
 ## Quick Start
 
@@ -24,42 +28,50 @@ Create and own the client at the application entry point:
 
 ```ts
 // main.ts
-import { createClient, withEndpoint } from '@defjs/core'
-import { createClientPlugin } from '@defjs/vue'
-import { createApp } from 'vue'
-import App from './App.vue'
+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:
+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:
 
 ```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());
+
+    const command = getUser({ id });
+    void client
+      .execute(command, { signal: abort.signal })
+      .then(([error, user]) => {
+        if (abort.signal.aborted) return;
+        if (error) {
+          name.value = error.message;
+          return;
+        }
+        name.value = user.name;
+      });
   },
   { immediate: true },
-)
+);
 </script>
 
 <template>
@@ -70,30 +82,38 @@ watch(
 Configure interceptors in core before installing the plugin:
 
 ```ts
-import { createClient, createHttpInterceptor, withEndpoint, withInterceptors } from '@defjs/core'
-import { createClientPlugin } from '@defjs/vue'
+import {
+  createClient,
+  createHttpInterceptor,
+  withEndpoint,
+  withInterceptors,
+} from "@defjs/core";
+import { createClientPlugin } from "@defjs/vue";
 
 const auth = createHttpInterceptor((request, next) => {
-  const headers = new Headers(request.headers)
-  headers.set('Authorization', `Bearer ${getAccessToken()}`)
-  return next({ ...request, headers })
-})
-
-const client = createClient(withEndpoint('https://api.example.com'), withInterceptors(auth))
-app.use(createClientPlugin(client))
+  const headers = new Headers(request.headers);
+  headers.set("Authorization", `Bearer ${getAccessToken()}`);
+  return next({ ...request, headers });
+});
+
+const client = createClient(
+  withEndpoint("https://api.example.com"),
+  withInterceptors(auth),
+);
+app.use(createClientPlugin(client));
 ```
 
 For a subtree override, use Vue's native provider with the public key:
 
 ```ts
-import { createClient, withEndpoint } from '@defjs/core'
-import { HTTP_CLIENT } from '@defjs/vue'
-import { provide } from 'vue'
+import { createClient, withEndpoint } from "@defjs/core";
+import { HTTP_CLIENT } from "@defjs/vue";
+import { provide } from "vue";
 
-provide(HTTP_CLIENT, createClient(withEndpoint('https://preview.example.com')))
+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.
+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
 
@@ -103,7 +123,17 @@ Creates a Vue plugin that provides the supplied client instance.
 
 ### `injectClient(): Client`
 
-Returns the client from the nearest Vue provider. Throws if no client was provided.
+```ts
+function injectClient(key?: InjectionKey<Client>): 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>`
 

package/index.d.ts

@@ -1,36 +1,48 @@
 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 an instance from `createClient`. Installing it calls `app.provide(HTTP_CLIENT, client)`, so components read the client with `injectClient()`.
  *
  * @param client - The Client instance 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 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.
  *
+ * @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.
- * @throws If no client was provided (plugin not installed).
+ * @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 an instance from `createClient`. Installing it calls `app.provide(HTTP_CLIENT, client)`, so components read the client with `injectClient()`.
 *
 * @param client - The Client instance 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,30 @@ 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 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.
 *
+* @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.
-* @throws If no client was provided (plugin not installed).
+* @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.1",
+  "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.4.0",
     "vue": ">=3.0.0"
   },
   "module": "./index.js",