katanakit-js 6.7.2 → 6.7.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +88 -12
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -29,7 +29,7 @@ In the browser, use jsDelivr **`/+esm`** so named exports and dependencies resol
|
|
|
29
29
|
| **esm.sh** | `https://esm.sh/katanakit-js` |
|
|
30
30
|
| **Raw ESM file** | `https://cdn.jsdelivr.net/npm/katanakit-js/dist/index.js` (needs bundler or import map) |
|
|
31
31
|
|
|
32
|
-
Pin a version in production (e.g. `@6.7.
|
|
32
|
+
Pin a version in production (e.g. `@6.7.4/+esm`). There is no IIFE/UMD build.
|
|
33
33
|
|
|
34
34
|
## Quick Start
|
|
35
35
|
|
|
@@ -70,7 +70,6 @@ export default defineApiConfig({
|
|
|
70
70
|
pokeapi: { baseUri: "https://pokeapi.co/api/v2", endpoints: { byId: "/pokemon/:id/" } },
|
|
71
71
|
debug: true, // boolean flags stay off the registry, on `config`
|
|
72
72
|
getPokemon: async function () {
|
|
73
|
-
// ^^^^^^^^ `function`, never an arrow
|
|
74
73
|
if (this.config.debug) console.log("fetching…");
|
|
75
74
|
return useFetch("pokeapi", "byId", { params: { id: 25 } });
|
|
76
75
|
},
|
|
@@ -355,10 +354,66 @@ const stop = useKatanaWatch(newProduct, () => checkValidations(), { deep: true }
|
|
|
355
354
|
- **Direct cache updates** — `setQueryData` for optimistic updates.
|
|
356
355
|
- **Prefetch** — `prefetchQuery` anticipates user actions.
|
|
357
356
|
|
|
357
|
+
## Design patterns
|
|
358
|
+
|
|
359
|
+
Services are **Singleton facades** with stable `use*` wrappers, and the classic
|
|
360
|
+
patterns stay swappable without leaving the functional API.
|
|
361
|
+
|
|
362
|
+
### Singleton + `use*` wrappers
|
|
363
|
+
|
|
364
|
+
```ts
|
|
365
|
+
import { LoggerService, useLogger } from "katanakit-js";
|
|
366
|
+
|
|
367
|
+
LoggerService.getInstance().useLog("Application started");
|
|
368
|
+
useLogger("Cache miss", undefined, "warn"); // thin wrapper over the singleton
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
### Strategy — access control and AI providers
|
|
372
|
+
|
|
373
|
+
```ts
|
|
374
|
+
import {
|
|
375
|
+
AccessService,
|
|
376
|
+
AgentService,
|
|
377
|
+
FlatAccessStrategy,
|
|
378
|
+
OpenAiCompatibleStrategy,
|
|
379
|
+
} from "katanakit-js";
|
|
380
|
+
|
|
381
|
+
// Swap the behavior of the shared singleton…
|
|
382
|
+
AccessService.getInstance().useSetStrategy(new FlatAccessStrategy());
|
|
383
|
+
|
|
384
|
+
// …or create an isolated instance (handy in tests).
|
|
385
|
+
const access = AccessService.create(new FlatAccessStrategy());
|
|
386
|
+
const agent = AgentService.create(new OpenAiCompatibleStrategy());
|
|
387
|
+
```
|
|
388
|
+
|
|
389
|
+
### Factory — one `QueryClient` per request (SSR)
|
|
390
|
+
|
|
391
|
+
```ts
|
|
392
|
+
import { QueryClientFactory } from "katanakit-js";
|
|
393
|
+
|
|
394
|
+
const client = QueryClientFactory.create(); // fresh cache per request
|
|
395
|
+
// QueryClientFactory.createShared() reuses the browser singleton
|
|
396
|
+
```
|
|
397
|
+
|
|
398
|
+
### Decorators — retry, TTL cache and timing traces
|
|
399
|
+
|
|
400
|
+
```ts
|
|
401
|
+
import { CacheDecorator, LoggerDecorator, RetryDecorator } from "katanakit-js";
|
|
402
|
+
|
|
403
|
+
const loadUser = RetryDecorator(LoggerDecorator(fetchUser, "user"), 2, 200);
|
|
404
|
+
const cached = CacheDecorator(loadUser, { ttlMs: 60_000 });
|
|
405
|
+
|
|
406
|
+
cached.useClearCache();
|
|
407
|
+
cached.useCacheSize();
|
|
408
|
+
```
|
|
409
|
+
|
|
410
|
+
`RetryDecorator` only retries **thrown** errors: Safe Result helpers never throw,
|
|
411
|
+
so unwrap them (e.g. with `useSafeQueryFn`) before composing.
|
|
412
|
+
|
|
358
413
|
## Features
|
|
359
414
|
|
|
360
415
|
- **Safe Results + helpers** — HTTP (and other fallible) operations return `{ data, error, ok }` instead of throwing; `useAttempt()`, `useTryJsonParse()` and `useErrorNormalize()` standardize boundaries and error shapes (see [Error Handling](https://docs.senseikatana.com/guides/errors))
|
|
361
|
-
- **Zod validation everywhere** — `types/` is the single source of truth, inferred from Zod schemas via `z.infer`; `useValidate()` turns any schema into a Safe Result and API adapters validate every response at the boundary
|
|
416
|
+
- **Zod validation everywhere** — `types/` is the single source of truth, inferred from Zod schemas via `z.infer`; every runtime schema is public under `katanakit-js/schemas`, `useValidate(schema, data)` turns any schema into a Safe Result, and API adapters validate every response at the boundary
|
|
362
417
|
- **Zero side effects** — importing any module is safe. No `fetch` calls, no `console.log`, no storage writes
|
|
363
418
|
- **Hexagonal architecture** — pure core, infrastructure adapters, framework adapters
|
|
364
419
|
- **Design patterns** — services are Singleton classes (`getInstance()`) with swappable Strategy implementations (`AccessService`, `AgentService`), a `QueryClientFactory` for per-request SSR clients, and composable Decorators exported from the main barrel: `RetryDecorator`, `CacheDecorator` (TTL memoization) and `LoggerDecorator` (timing traces)
|
|
@@ -810,15 +865,36 @@ See [Getting Started](https://docs.senseikatana.com/guides/getting-started) for
|
|
|
810
865
|
|
|
811
866
|
## Framework Adapters
|
|
812
867
|
|
|
813
|
-
|
|
814
|
-
|
|
815
|
-
|
|
|
816
|
-
|
|
|
817
|
-
| **
|
|
818
|
-
| **
|
|
819
|
-
| **
|
|
820
|
-
| **
|
|
821
|
-
|
|
868
|
+
### Server & meta-framework
|
|
869
|
+
|
|
870
|
+
| Adapter | Import | Description |
|
|
871
|
+
| ----------- | ----------------------------------------------- | ------------------------------------------------------- |
|
|
872
|
+
| **Express** | `katanakit-js/adapters/express` | Reference server with CORS and hardened headers |
|
|
873
|
+
| **Bun** | `katanakit-js/adapters/bun` | `Bun.serve` route table + dummyjson.com demo |
|
|
874
|
+
| **Nuxt** | `katanakit-js/adapters/nuxt` | `useUnwrap`, `useSafeResponse`, `useEventResponse` |
|
|
875
|
+
| **Astro** | `katanakit-js` or `katanakit-js/adapters/astro` | `AstroService`, `RssService` |
|
|
876
|
+
|
|
877
|
+
### UI frameworks
|
|
878
|
+
|
|
879
|
+
Each subpath is a complete entry point: it re-exports the query client helpers
|
|
880
|
+
and adds the framework's native reactivity over TanStack Query Core.
|
|
881
|
+
|
|
882
|
+
| Adapter | Import | Bindings |
|
|
883
|
+
| ----------- | ------------------------------ | --------------------------------------------------- |
|
|
884
|
+
| **React** | `katanakit-js/adapters/react` | `useQuery`, `useMutation`, `useRequest`, `useWatch` |
|
|
885
|
+
| **Vue** | `katanakit-js/adapters/vue` | `useQuery`, `useMutation`, `useRequest`, `useWatch` |
|
|
886
|
+
| **Solid** | `katanakit-js/adapters/solid` | `useQuery`, `useMutation`, `useRequest`, `useWatch` |
|
|
887
|
+
| **Svelte** | `katanakit-js/adapters/svelte` | `useQuery`, `useMutation`, `useRequest`, `useWatch` |
|
|
888
|
+
| **Angular** | `katanakit-js/adapters/angular` | `useQuery`, `useMutation`, `useRequest`, `useWatch` |
|
|
889
|
+
| **Vanilla** | `katanakit-js/adapters/vanilla` | Raw `QueryObserver` / `MutationObserver`, no framework |
|
|
890
|
+
|
|
891
|
+
### Assistant & messaging
|
|
892
|
+
|
|
893
|
+
| Adapter | Import | Description |
|
|
894
|
+
| ------------- | --------------------------------- | ------------------------------------------------------------------ |
|
|
895
|
+
| **Assistant** | `katanakit-js/adapters/assistant` | REST digital assistant (`useStartAssistant`) |
|
|
896
|
+
| **Telegram** | `katanakit-js/adapters/telegram` | BotFather bot (`defineTelegramConfig`, `useStartTelegramPolling`) |
|
|
897
|
+
| **WhatsApp** | `katanakit-js/adapters/whatsapp` | Meta Cloud API (`defineWhatsAppConfig`, `useStartWhatsApp`) |
|
|
822
898
|
|
|
823
899
|
## UI and Auth Adapters
|
|
824
900
|
|
package/package.json
CHANGED