katanakit-js 2.1.6 → 2.2.1

package/CHANGELOG.md

@@ -13,6 +13,11 @@ Current development version. This is the first release published under the
 
 ### Added
 
+- **Vue adapter** — new `katanakit-js/adapters/vue` subpath exporting the
+  `useKatanaFetch` composable, which bridges KatanaKit Safe Results to Vue 3
+  reactivity (`data`, `error`, `loading`, `refetch`). Accepts a reactive `Ref`
+  of `UrlOptions` and refetches automatically on change. `vue` is an optional
+  peer dependency.
 - **Nuxt adapter** — new `katanakit-js/adapters/nuxt` subpath exporting three
   pure helpers that bridge KatanaKit Safe Results to Nuxt/Nitro server routes:
   `useUnwrap(result, context?)`, `useSafeResponse(result)` and

package/README.md

@@ -6,9 +6,9 @@ Observer, Factory, Strategy, Facade and Adapter).
 
 It runs in the browser, in Node.js (>= 22.18) and in Bun, ships with an Astro
 `getStaticPaths` adapter, an RSS 2.0 generator, a site-config/SEO module, an
-optional Express server reference and a Nuxt (Nitro/H3) adapter. Importing a
-module never triggers side effects, and every async operation returns a **Safe
-Result** instead of throwing.
+optional Express server reference, a Nuxt (Nitro/H3) adapter and a Vue 3
+composable. Importing a module never triggers side effects, and every async
+operation returns a **Safe Result** instead of throwing.
 
 - **Version:** 2.1.4
 - **npm package:** `katanakit-js`
@@ -36,8 +36,8 @@ storage and DOM across every framework.
   on HTTP errors.
 - **Hexagonal architecture** — a pure `core` layer (services), an
   `infrastructure` layer (browser/runtime adapters), an `adapters` layer
-  (Astro, Express, Nuxt), a `config` layer (site config + SEO) and a single
-  source of truth for contracts and types in `src/types/`.
+  (Astro, Express, Nuxt, Vue), a `config` layer (site config + SEO) and a
+  single source of truth for contracts and types in `src/types/`.
 - **Design patterns** — Singleton facades, Strategy (logger, storage,
   crypto/UUID), Factory (errors, debounce/throttle), Observer (signals,
   IntersectionObserver, media queries), Facade and Adapter, all exposed as
@@ -77,6 +77,9 @@ published as package **subpaths** of the same `katanakit-js` package:
 // Nuxt / Nitro adapter helpers (no extra dependency; h3 ships with Nuxt)
 import { useUnwrap } from "katanakit-js/adapters/nuxt";
 
+// Vue 3 composable (requires vue as a peer dependency)
+import { useKatanaFetch } from "katanakit-js/adapters/vue";
+
 // Express reference server (requires express as a peer dependency)
 import { ServerExpress } from "katanakit-js/adapters/express";
 ```
@@ -347,6 +350,54 @@ JSON response object) and `useEventResponse(event, result)` (set the H3 event
 status code and return data/error). See the
 [API Reference](docs/API-Reference.md#nuxt-adapter--katanakit-jsadaptersnuxt).
 
+## Vue adapter
+
+`useKatanaFetch` is a Vue 3 composable that bridges KatanaKit's Safe Results to
+Vue's reactivity system. It exposes `data`, `error`, `loading` and a `refetch`
+function, and it never throws on HTTP errors.
+
+```ts
+import { useInit } from "katanakit-js";
+import { useKatanaFetch } from "katanakit-js/adapters/vue";
+
+useInit({
+  pokeapi: {
+    baseUri: "https://pokeapi.co/api/v2",
+    endpoints: { pokemonById: "/pokemon/:id/" },
+  },
+});
+```
+
+```vue
+<script setup lang="ts">
+import { useKatanaFetch } from "katanakit-js/adapters/vue";
+
+interface Pokemon { name: string; id: number; }
+
+const { data: pokemon, error, loading } = useKatanaFetch<Pokemon>(
+  "pokeapi",
+  "pokemonById",
+  { params: { id: 25 } },
+);
+</script>
+
+<template>
+  <div v-if="loading">Loading…</div>
+  <div v-else-if="error">{{ error.message }}</div>
+  <div v-else>{{ pokemon?.name }}</div>
+</template>
+```
+
+Pass a `Ref` as the options argument to refetch automatically when it changes:
+
+```ts
+const id = ref(25);
+const { data } = useKatanaFetch("pokeapi", "pokemonById", computed(() => ({ params: { id: id.value } })));
+```
+
+`vue` is an optional peer dependency — install it only if you use this adapter.
+See the [API Reference](docs/API-Reference.md#vue-adapter--katanakit-jsadaptersvue).
+
 ## Express server (optional)
 
 The Express reference adapter is exposed only through its own subpath so it
@@ -389,11 +440,12 @@ project. A `ProductController` and a demo `router` are also exported.
 | SEO       | `useHeadTags` and friends   | `useGenerateMetaTags`, `useTitle`, `useRssHeadLink` + typed `SiteConfig` |
 | Config    | `siteConfig` / `SiteConfig` | single source for site metadata, RSS and SEO defaults                |
 | Nuxt      | `katanakit-js/adapters/nuxt`| `useUnwrap`, `useSafeResponse`, `useEventResponse` (pure functions)  |
+| Vue       | `katanakit-js/adapters/vue` | `useKatanaFetch` composable (`data`, `error`, `loading`, `refetch`)  |
 | Server    | `katanakit-js/adapters/express` | `ServerExpress`, `router`, `ProductController` (optional reference) |
 
 The Astro, RSS, SEO and config modules plus all core/infrastructure services
-are re-exported from the main barrel. The Nuxt and Express adapters are only
-available through their subpaths.
+are re-exported from the main barrel. The Nuxt, Vue and Express adapters are
+only available through their subpaths.
 
 ## Project structure (hexagonal)
 
@@ -412,10 +464,11 @@ katanakit/
 │   ├── adapters/             # framework adapters
 │   │   ├── astro/            #   AstroService + RssService
 │   │   ├── express/          #   ServerExpress reference (subpath export)
-│   │   └── nuxt/             #   Nuxt helpers (subpath export)
+│   │   ├── nuxt/             #   Nuxt helpers (subpath export)
+│   │   └── vue/              #   Vue composable (subpath export)
 │   ├── config/               # siteConfig (SiteConfig) + SEO helpers
 │   └── prisma/               # Prisma schema, contract types and db client
-├── tests/                    # Vitest suite (57 tests across 7 files)
+├── tests/                    # Vitest suite (60 tests across 8 files)
 ├── examples/                 # runnable demos
 ├── docs/                     # Getting Started, Architecture, API Reference, Roadmap
 ├── CONTRIBUTING.md

package/dist/adapters/vue/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./vue.service.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/vue/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/vue/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC"}

package/dist/adapters/vue/index.js

@@ -0,0 +1,2 @@
+export * from "./vue.service.js";
+//# sourceMappingURL=index.js.map

package/dist/adapters/vue/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adapters/vue/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC"}

package/dist/adapters/vue/vue.service.d.ts

@@ -0,0 +1,41 @@
+import { type MaybeRef, type Ref } from "vue";
+import type { ApiError, UrlOptions } from "../../types/index.js";
+/**
+ * Reactive state exposed by the {@link useKatanaFetch} composable.
+ */
+export interface KatanaFetchState<T> {
+    /** The resolved data on success, `null` otherwise. */
+    data: Ref<T | null>;
+    /** The Safe Result error on failure, `null` otherwise. */
+    error: Ref<ApiError | null>;
+    /** Whether a request is in flight. */
+    loading: Ref<boolean>;
+    /** Re-runs the request manually. */
+    refetch: () => Promise<void>;
+}
+/**
+ * Vue 3 composable that wraps KatanaKit's `useGet` with the reactivity system.
+ * It bridges the Safe Result pattern to idiomatic Vue state (`data`, `error`,
+ * `loading`) and never throws on HTTP errors.
+ *
+ * When `options` is a Vue `Ref`, the request re-runs automatically whenever the
+ * ref changes (deep watch), so URL params or query params can drive refetching.
+ *
+ * @param apiName - Name of the registered API (see `useInit`).
+ * @param endpointName - Name of the endpoint inside that API.
+ * @param options - Optional `UrlOptions` (path/query params), plain or reactive.
+ * @returns Reactive `{ data, error, loading, refetch }`.
+ *
+ * @example
+ * ```ts
+ * import { useKatanaFetch } from "katanakit-js/adapters/vue";
+ *
+ * const { data, error, loading } = useKatanaFetch<{ name: string }>(
+ *   "pokeapi",
+ *   "pokemonById",
+ *   { params: { id: 25 } },
+ * );
+ * ```
+ */
+export declare function useKatanaFetch<T>(apiName: string, endpointName: string, options?: MaybeRef<UrlOptions>): KatanaFetchState<T>;
+//# sourceMappingURL=vue.service.d.ts.map

package/dist/adapters/vue/vue.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vue.service.d.ts","sourceRoot":"","sources":["../../../src/adapters/vue/vue.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,QAAQ,EAAE,KAAK,GAAG,EAAiC,MAAM,KAAK,CAAC;AAGpF,OAAO,KAAK,EAAE,QAAQ,EAAe,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAE9E;;GAEG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC;IAClC,sDAAsD;IACtD,IAAI,EAAE,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACpB,0DAA0D;IAC1D,KAAK,EAAE,GAAG,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IAC5B,sCAAsC;IACtC,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;IACtB,oCAAoC;IACpC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC/B,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,QAAQ,CAAC,UAAU,CAAC,GAC5B,gBAAgB,CAAC,CAAC,CAAC,CA6BrB"}

package/dist/adapters/vue/vue.service.js

@@ -0,0 +1,51 @@
+import { isRef, ref, shallowRef, unref, watch } from "vue";
+import { useGet } from "../../core/services/http.service.js";
+/**
+ * Vue 3 composable that wraps KatanaKit's `useGet` with the reactivity system.
+ * It bridges the Safe Result pattern to idiomatic Vue state (`data`, `error`,
+ * `loading`) and never throws on HTTP errors.
+ *
+ * When `options` is a Vue `Ref`, the request re-runs automatically whenever the
+ * ref changes (deep watch), so URL params or query params can drive refetching.
+ *
+ * @param apiName - Name of the registered API (see `useInit`).
+ * @param endpointName - Name of the endpoint inside that API.
+ * @param options - Optional `UrlOptions` (path/query params), plain or reactive.
+ * @returns Reactive `{ data, error, loading, refetch }`.
+ *
+ * @example
+ * ```ts
+ * import { useKatanaFetch } from "katanakit-js/adapters/vue";
+ *
+ * const { data, error, loading } = useKatanaFetch<{ name: string }>(
+ *   "pokeapi",
+ *   "pokemonById",
+ *   { params: { id: 25 } },
+ * );
+ * ```
+ */
+export function useKatanaFetch(apiName, endpointName, options) {
+    const data = shallowRef(null);
+    const error = ref(null);
+    const loading = ref(true);
+    const refetch = async () => {
+        loading.value = true;
+        error.value = null;
+        const result = await useGet(apiName, endpointName, unref(options));
+        if (result.ok) {
+            data.value = result.data;
+        }
+        else {
+            error.value = result.error;
+        }
+        loading.value = false;
+    };
+    // Refetch automatically when a reactive options ref changes.
+    if (isRef(options)) {
+        watch(options, refetch, { deep: true });
+    }
+    // Initial fetch on setup.
+    void refetch();
+    return { data, error, loading, refetch };
+}
+//# sourceMappingURL=vue.service.js.map

package/dist/adapters/vue/vue.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vue.service.js","sourceRoot":"","sources":["../../../src/adapters/vue/vue.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAA2B,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,CAAC;AAEpF,OAAO,EAAE,MAAM,EAAE,MAAM,qCAAqC,CAAC;AAiB7D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,cAAc,CAC7B,OAAe,EACf,YAAoB,EACpB,OAA8B;IAE9B,MAAM,IAAI,GAAG,UAAU,CAAW,IAAI,CAAC,CAAC;IACxC,MAAM,KAAK,GAAG,GAAG,CAAkB,IAAI,CAAC,CAAC;IACzC,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;IAE1B,MAAM,OAAO,GAAG,KAAK,IAAmB,EAAE;QACzC,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC;QACrB,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC;QAEnB,MAAM,MAAM,GAAmB,MAAM,MAAM,CAAI,OAAO,EAAE,YAAY,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAEtF,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC;QAC1B,CAAC;aAAM,CAAC;YACP,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;QAC5B,CAAC;QAED,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC;IACvB,CAAC,CAAC;IAEF,6DAA6D;IAC7D,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QACpB,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IACzC,CAAC;IAED,0BAA0B;IAC1B,KAAK,OAAO,EAAE,CAAC;IAEf,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAC1C,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "katanakit-js",
-	"version": "2.1.6",
+	"version": "2.2.1",
 	"description": "KatanaKit — a sharp, framework-agnostic TypeScript service toolkit organized with hexagonal architecture.",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -18,6 +18,10 @@
 		"./adapters/nuxt": {
 			"types": "./dist/adapters/nuxt/index.d.ts",
 			"import": "./dist/adapters/nuxt/index.js"
+		},
+		"./adapters/vue": {
+			"types": "./dist/adapters/vue/index.d.ts",
+			"import": "./dist/adapters/vue/index.js"
 		}
 	},
 	"files": [
@@ -63,6 +67,7 @@
 		"astro",
 		"express",
 		"nuxt",
+		"vue",
 		"singleton",
 		"observer",
 		"factory"
@@ -80,7 +85,8 @@
 		"@prisma/orm-postgres": ">=8.0.0-rc.0",
 		"cors": ">=2.8.0",
 		"dotenv": ">=16.0.0",
-		"express": ">=5.0.0"
+		"express": ">=5.0.0",
+		"vue": ">=3.0.0"
 	},
 	"peerDependenciesMeta": {
 		"@prisma/orm-postgres": {
@@ -94,6 +100,9 @@
 		},
 		"express": {
 			"optional": true
+		},
+		"vue": {
+			"optional": true
 		}
 	},
 	"devDependencies": {
@@ -112,6 +121,7 @@
 		"prisma": "8.0.0-rc.12",
 		"typescript": "^7.0.2",
 		"vite": "^8.2.2",
-		"vitest": "^5.0.0"
+		"vitest": "^5.0.0",
+		"vue": "^3.5.0"
 	}
 }