katanakit-js 4.0.4 → 5.2.0

package/README.md

@@ -7,7 +7,7 @@ A sharp, framework-agnostic TypeScript service toolkit organized with hexagonal
 ```bash
 npm install katanakit-js
 # or
-bun add katanakit-js
+pnpm add katanakit-js
 # or
 bun add katanakit-js
 ```
@@ -323,11 +323,151 @@ const stop = useKatanaWatch(newProduct, () => checkValidations(), { deep: true }
 
 ## Features
 
-- **Safe Results** — HTTP (and other fallible) operations return `{ data, error, ok }` instead of throwing
+- **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))
+- **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
 - **Zero side effects** — importing any module is safe. No `fetch` calls, no `console.log`, no storage writes
 - **Hexagonal architecture** — pure core, infrastructure adapters, framework adapters
 - **Tree-shakeable** — destructured re-exports from Singleton facades
 - **SSR-safe** — all infrastructure adapters guard or fall back gracefully in server environments
+- **Filesystem (Node/Bun)** — `useReadFile`, `useWriteFile`, `useReadJsonFile`, `useReadModuleJson` and friends return Safe Results with native errno codes, loaded lazily through dynamic `import()` and guarded by `useIsNode()`
+- **Fake data (optional)** — `useFakeVehicle`, `useFakeEmail`, `useFakeList`, … via an optional, lazy-loaded `@faker-js/faker` peer
+
+## Filesystem (Node/Bun)
+
+Node-only helpers that wrap `node:fs/promises` and `node:path` with the Safe
+Result contract. Built-ins load through dynamic `import()`, so importing them is
+browser-safe; outside Node/Bun every fallible call returns `ERR_FS_UNAVAILABLE`
+instead of throwing.
+
+```ts
+import {
+  useEnsureDir,
+  useReadDir,
+  useReadJsonFile,
+  useReadModuleJson,
+  useWriteJsonFile,
+} from "katanakit-js";
+import { z } from "zod";
+
+const BooksSchema = z.array(z.object({ title: z.string() }));
+
+// Read relative to the current module (the __dirname pattern, without __dirname)
+const result = await useReadModuleJson(import.meta.url, "../data/books.json", BooksSchema);
+
+if (result.ok) {
+  console.log(result.data);
+} else {
+  console.error(result.error.code, result.error.message); // ENOENT | ERR_VALIDATION | ...
+}
+
+// Or with an explicit path (relative paths resolve against process.cwd())
+await useEnsureDir("data/cache");
+await useWriteJsonFile("data/cache/books.json", [{ title: "Kata" }]);
+const books = await useReadJsonFile("data/cache/books.json", BooksSchema);
+const files = await useReadDir("data/cache", { recursive: true });
+```
+
+| Group | Helpers |
+| ----- | ------- |
+| Read | `useReadFile`, `useReadFileBuffer`, `useReadJsonFile`, `useReadModuleFile`, `useReadModuleJson` |
+| Write | `useWriteFile`, `useAppendFile`, `useWriteJsonFile`, `useEnsureDir` |
+| Inspect | `useFileExists`, `useGetFileStats`, `useReadDir` |
+| Move / delete | `useCopyFile`, `useMoveFile`, `useRemoveFile`, `useRemoveDir` |
+| Paths | `useGetDirname`, `useResolvePath`, `useJoinPath`, `useGetRelativePath`, `useGetBasename`, `useGetFileExtension`, `useGetCwd`, `useIsNode` |
+
+## Fake data (optional)
+
+`@faker-js/faker` is an **optional peer dependency**: these helpers load it
+through dynamic `import()` on first call, so install it only if you use them
+(`bun add @faker-js/faker` / `npm install @faker-js/faker`).
+
+| Group             | Helpers                                                                                                        |
+| ----------------- | -------------------------------------------------------------------------------------------------------------- |
+| People / internet | `useFakeFullName`, `useFakeFirstName`, `useFakeLastName`, `useFakeEmail`, `useFakePhone`, `useFakeCompanyName`, `useFakeUrl` |
+| Values            | `useFakeUuid`, `useFakeText`, `useFakeNumber`, `useFakeBoolean`, `useFakeDate`, `useFakeVehicle`                |
+| Collections       | `useFakeList(factory, count)` — the factory receives the zero-based index                                       |
+| Reproducibility   | `useFakeSeed(seed?)`, `useFakeSetDefaultRefDate(refDate?)`                                                      |
+
+### Reproducible seeds
+
+`useFakeSeed(42)` sets the seed **and returns it**. Call it with no arguments to
+roll a fresh random seed (also returned) — log it in CI and pass it back later
+to replay the exact run. `useFakeSetDefaultRefDate("2026-01-01")` pins the
+reference date used by date helpers. Same seed + same reference date + same
+call order + same faker major = identical output.
+
+```ts
+import { useFakeSeed, useFakeSetDefaultRefDate, useFakeUuid } from "katanakit-js";
+
+const seed = await useFakeSeed(); // e.g. 1696121567592875 — log it in CI
+await useFakeSetDefaultRefDate("2026-01-01");
+
+await useFakeSeed(seed); // replay the exact same sequence
+const id = await useFakeUuid();
+```
+
+### Seed data (users, products, orders)
+
+Compose the helpers with `useFakeList` to build realistic fixtures, then write
+them anywhere with the [filesystem helpers](#filesystem-nodebun):
+
+```ts
+import {
+  useEnsureDir,
+  useFakeDate,
+  useFakeEmail,
+  useFakeFullName,
+  useFakeList,
+  useFakeNumber,
+  useFakeSeed,
+  useFakeSetDefaultRefDate,
+  useFakeText,
+  useFakeUuid,
+  useWriteJsonFile,
+} from "katanakit-js";
+
+await useFakeSeed(42);
+await useFakeSetDefaultRefDate("2026-01-01");
+
+const users = await useFakeList(
+  async () => ({
+    id: await useFakeUuid(),
+    fullName: await useFakeFullName(),
+    email: await useFakeEmail(),
+    createdAt: (await useFakeDate("2024-01-01")).toISOString(),
+  }),
+  5,
+);
+
+const products = await useFakeList(
+  async () => ({
+    id: await useFakeUuid(),
+    name: await useFakeText(3),
+    price: await useFakeNumber(5, 250),
+    stock: await useFakeNumber(0, 120),
+  }),
+  8,
+);
+
+// Relations: the factory receives the index
+const orders = await useFakeList(
+  async (index) => ({
+    id: await useFakeUuid(),
+    userId: users[index % users.length].id,
+    productId: products[index % products.length].id,
+    quantity: await useFakeNumber(1, 6),
+    placedAt: (await useFakeDate("2025-01-01")).toISOString(),
+  }),
+  12,
+);
+
+await useEnsureDir("data/seed");
+await useWriteJsonFile("data/seed/users.json", users);
+// feed the arrays to your seeder: prisma.user.createMany({ data: users }), ...
+```
+
+A runnable version (users, products and orders with relations, written as JSON)
+lives in [`examples/seed/`](./examples/seed/README.md).
 
 ## AI assistant (Kitt)
 
@@ -629,7 +769,7 @@ import { useUnwrap } from "katanakit-js/adapters/nuxt"; // Nuxt only
 </script>
 ```
 
-See [Getting Started](https://docs.senseikatana.com/docs/guides/getting-started/) for full recipes.
+See [Getting Started](https://docs.senseikatana.com/guides/getting-started) for full recipes.
 
 ## Framework Adapters
 
@@ -652,6 +792,11 @@ All functions return `FetchResult<T>` — the same Safe Result pattern used by t
 | ------------- | --------------------------------- | ----------------------------------------------------------------- |
 | **Notion**    | `katanakit-js/adapters/notion`    | Pages, databases, blocks, search with cursor pagination           |
 | **WordPress** | `katanakit-js/adapters/wordpress` | Posts, pages, media, categories, tags, comments, users, batch ops |
+| **InsForge**  | `katanakit-js/adapters/insforge`  | Database fallback, storage buckets and edge functions             |
+
+All REST adapters validate responses with Zod: malformed payloads return a typed `502`
+Safe Result instead of untyped garbage, and invalid inputs are rejected with `400`
+before any network call.
 
 ### Notion
 
@@ -1217,6 +1362,34 @@ const full = await useWpGetPosts({
 | **Next.js** | [`examples/wordpress/next-[slug].tsx`](https://github.com/senseikatana/katanakit-js/tree/main/examples/wordpress/next-[slug].tsx)       | Dynamic `[slug]` page                                              |
 | **Node.js** | [`examples/wordpress/demo.ts`](https://github.com/senseikatana/katanakit-js/tree/main/examples/wordpress/demo.ts)                       | Runnable demo covering all WP operations, `_fields`, `_embed`, ACF |
 
+### InsForge (database fallback)
+
+InsForge is supported as the **database fallback** (the primary data layer is Cloudflare),
+plus object storage and edge functions. The adapter wraps the official SDK in the same
+Safe Result contract, validates every input, and refuses mass writes (update/delete
+require non-empty filters).
+
+```ts
+import { useInitInsforge, useIfSelect, useIfInsert } from "katanakit-js/adapters/insforge";
+
+// Server-only admin client (apiKey), or browser-safe client (anonKey)
+useInitInsforge({ baseUrl: process.env.INSFORGE_URL!, apiKey: process.env.INSFORGE_API_KEY! });
+
+const posts = await useIfSelect<{ id: number; title: string }>({
+	table: "posts",
+	filters: { author_id: 7 },
+	order: { column: "created_at", ascending: false },
+	limit: 10,
+});
+if (posts.ok) console.log(posts.data);
+
+const created = await useIfInsert("posts", [{ title: "Hello" }]);
+```
+
+Storage (`useIfUpload`, `useIfDownload`, `useIfRemove`, `useIfListObjects`,
+`useIfGetPublicUrl`) and edge functions (`useIfInvokeFunction`) follow the same pattern.
+Install the optional peer with `bun add @insforge/sdk`.
+
 ## Contributing
 
 We welcome contributions from the community! Whether it's fixing a bug, adding
@@ -1253,14 +1426,15 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development contract.
 
 ## Documentation
 
-The docs site is deployed with Cloudflare Pages at [docs.senseikatana.com](https://docs.senseikatana.com/).
+The docs site is built with **VitePress** from [`docs/`](./docs) and deployed with Cloudflare Pages at [docs.senseikatana.com](https://docs.senseikatana.com/). Run it locally with `bun run docs:dev`.
 
-- [Getting Started](https://docs.senseikatana.com/docs/guides/getting-started/)
-- [Architecture](https://docs.senseikatana.com/docs/guides/architecture/)
-- [UI Kit (Katana UI)](https://docs.senseikatana.com/docs/ui-kit/)
-- [API Reference](https://docs.senseikatana.com/docs/api/)
-- [Roadmap](https://docs.senseikatana.com/docs/guides/roadmap/)
-- [Changelog](https://docs.senseikatana.com/docs/changelog/)
+- [Getting Started](https://docs.senseikatana.com/guides/getting-started)
+- [Error Handling](https://docs.senseikatana.com/guides/errors)
+- [Architecture](https://docs.senseikatana.com/guides/architecture)
+- [UI Kit (Katana UI)](https://docs.senseikatana.com/ui-kit/)
+- [API Reference](https://docs.senseikatana.com/api/)
+- [Roadmap](https://docs.senseikatana.com/guides/roadmap)
+- [Changelog](https://docs.senseikatana.com/changelog)
 
 ## License
 

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

@@ -0,0 +1,3 @@
+export type { IfConfig, IfInsertRows, IfInvokeOptions, IfListOptions, IfOrder, IfRpcCall, IfStorageRef, IfTableQuery, IfUpdatePatch, IfWriteQuery, } from "../../types/index.js";
+export { useGetInsforgeClient, useIfDelete, useIfDownload, useIfGetPublicUrl, useIfInsert, useIfInvokeFunction, useIfListObjects, useIfRemove, useIfRpc, useIfSelect, useIfUpdate, useIfUpload, useInitInsforge, } from "./insforge.service.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/insforge/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACX,QAAQ,EACR,YAAY,EACZ,eAAe,EACf,aAAa,EACb,OAAO,EACP,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,YAAY,GACZ,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACN,oBAAoB,EACpB,WAAW,EACX,aAAa,EACb,iBAAiB,EACjB,WAAW,EACX,mBAAmB,EACnB,gBAAgB,EAChB,WAAW,EACX,QAAQ,EACR,WAAW,EACX,WAAW,EACX,WAAW,EACX,eAAe,GACf,MAAM,uBAAuB,CAAC"}

package/dist/adapters/insforge/index.js

@@ -0,0 +1,2 @@
+export { useGetInsforgeClient, useIfDelete, useIfDownload, useIfGetPublicUrl, useIfInsert, useIfInvokeFunction, useIfListObjects, useIfRemove, useIfRpc, useIfSelect, useIfUpdate, useIfUpload, useInitInsforge, } from "./insforge.service.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adapters/insforge/index.ts"],"names":[],"mappings":"AAYA,OAAO,EACN,oBAAoB,EACpB,WAAW,EACX,aAAa,EACb,iBAAiB,EACjB,WAAW,EACX,mBAAmB,EACnB,gBAAgB,EAChB,WAAW,EACX,QAAQ,EACR,WAAW,EACX,WAAW,EACX,WAAW,EACX,eAAe,GACf,MAAM,uBAAuB,CAAC"}

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

@@ -0,0 +1,116 @@
+import { type InsForgeClient } from "@insforge/sdk";
+import type { FetchResult, IfConfig, IfInsertRows, IfInvokeOptions, IfListOptions, IfRpcCall, IfStorageRef, IfTableQuery, IfUpdatePatch, IfWriteQuery } from "../../types/index.js";
+/**
+ * Registers the InsForge client. Call once per app. Prefer `apiKey`
+ * (server-only, admin) or `anonKey` (browser-safe) depending on the runtime.
+ *
+ * @param config - Backend URL + credentials + optional schema.
+ * @throws {Error} If the config fails validation.
+ *
+ * @example
+ * ```ts
+ * import { useInitInsforge } from "katanakit-js/adapters/insforge";
+ *
+ * useInitInsforge({ baseUrl: "https://app.insforge.app", anonKey: "…" });
+ * ```
+ */
+export declare function useInitInsforge(config: IfConfig): void;
+/**
+ * Returns the initialized client (or `null` before `useInitInsforge`).
+ * Exposed for advanced use — the wrappers cover the supported surface.
+ *
+ * @returns The InsForge client or `null`.
+ */
+export declare function useGetInsforgeClient(): InsForgeClient | null;
+/**
+ * Reads rows from a table with equality filters, ordering and pagination.
+ *
+ * @param query - Table, columns, filters, order, limit and offset.
+ * @returns Safe Result with the rows.
+ *
+ * @example
+ * ```ts
+ * const result = await useIfSelect<Post>({ table: "posts", filters: { author_id: 7 } });
+ * ```
+ */
+export declare function useIfSelect<T = Record<string, unknown>>(query: IfTableQuery): Promise<FetchResult<T[]>>;
+/**
+ * Inserts one or more rows and returns the created rows.
+ *
+ * @param table - Table name.
+ * @param rows - Rows to insert (at least one).
+ * @param schema - Optional schema override.
+ * @returns Safe Result with the inserted rows.
+ */
+export declare function useIfInsert<T = Record<string, unknown>>(table: string, rows: IfInsertRows, schema?: string): Promise<FetchResult<T[]>>;
+/**
+ * Updates rows matching the filters and returns the updated rows.
+ * Filters are REQUIRED — mass updates are refused at validation time.
+ *
+ * @param query - Table + mandatory filters (+ optional schema).
+ * @param patch - Column patch (must not be empty).
+ * @returns Safe Result with the updated rows.
+ */
+export declare function useIfUpdate<T = Record<string, unknown>>(query: IfWriteQuery, patch: IfUpdatePatch): Promise<FetchResult<T[]>>;
+/**
+ * Deletes rows matching the filters and returns the deleted rows.
+ * Filters are REQUIRED — mass deletes are refused at validation time.
+ *
+ * @param query - Table + mandatory filters (+ optional schema).
+ * @returns Safe Result with the deleted rows.
+ */
+export declare function useIfDelete<T = Record<string, unknown>>(query: IfWriteQuery): Promise<FetchResult<T[]>>;
+/**
+ * Calls a Postgres function (RPC).
+ *
+ * @param call - Function name, params and optional schema.
+ * @returns Safe Result with the function output.
+ */
+export declare function useIfRpc<T = unknown>(call: IfRpcCall): Promise<FetchResult<T>>;
+/**
+ * Uploads a file to a bucket (standard PUT semantics: same key replaces).
+ *
+ * @param ref - Bucket + object key.
+ * @param file - File or Blob to upload.
+ * @returns Safe Result with the stored file metadata.
+ */
+export declare function useIfUpload(ref: IfStorageRef, file: File | Blob): Promise<FetchResult<Record<string, unknown>>>;
+/**
+ * Downloads a file from a bucket.
+ *
+ * @param ref - Bucket + object key.
+ * @returns Safe Result with the file as a Blob.
+ */
+export declare function useIfDownload(ref: IfStorageRef): Promise<FetchResult<Blob>>;
+/**
+ * Removes a file from a bucket.
+ *
+ * @param ref - Bucket + object key.
+ * @returns Safe Result with the deletion response.
+ */
+export declare function useIfRemove(ref: IfStorageRef): Promise<FetchResult<Record<string, unknown>>>;
+/**
+ * Lists objects in a bucket.
+ *
+ * @param bucket - Bucket name.
+ * @param options - Prefix, search, limit and offset.
+ * @returns Safe Result with the listing.
+ */
+export declare function useIfListObjects(bucket: string, options?: IfListOptions): Promise<FetchResult<Record<string, unknown>>>;
+/**
+ * Builds the public URL for an object in a public bucket (no network call).
+ *
+ * @param ref - Bucket + object key.
+ * @returns Safe Result with `{ publicUrl }`.
+ */
+export declare function useIfGetPublicUrl(ref: IfStorageRef): FetchResult<{
+    publicUrl: string;
+}>;
+/**
+ * Invokes an edge function.
+ *
+ * @param options - Function slug + optional JSON body.
+ * @returns Safe Result with the function response.
+ */
+export declare function useIfInvokeFunction<T = unknown>(options: IfInvokeOptions): Promise<FetchResult<T>>;
+//# sourceMappingURL=insforge.service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"insforge.service.d.ts","sourceRoot":"","sources":["../../../src/adapters/insforge/insforge.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmC,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAgBrF,OAAO,KAAK,EAEX,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,eAAe,EACf,aAAa,EACb,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,MAAM,sBAAsB,CAAC;AAkJ9B;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI,CActD;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,cAAc,GAAG,IAAI,CAE5D;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5D,KAAK,EAAE,YAAY,GACjB,OAAO,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAwB3B;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5D,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,YAAY,EAClB,MAAM,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAe3B;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5D,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAyB3B;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5D,KAAK,EAAE,YAAY,GACjB,OAAO,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAc3B;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAYpF;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAChC,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,IAAI,GAAG,IAAI,GACf,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAW/C;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAsBjF;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAChC,GAAG,EAAE,YAAY,GACf,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAW/C;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACrC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,aAAa,GACrB,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAa/C;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,YAAY,GAAG,WAAW,CAAC;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAiBvF;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,GAAG,OAAO,EACpD,OAAO,EAAE,eAAe,GACtB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAazB"}