klaim 1.12.48 → 1.12.49

package/docs/codedocs/api-reference/klaim.md

@@ -0,0 +1,105 @@
+---
+title: "Klaim Runtime"
+description: "Reference for the exported `Klaim` runtime object and the dynamic route call shapes it exposes."
+---
+
+Source: `src/core/Klaim.ts`
+
+Import path:
+
+```typescript
+import { Klaim } from "klaim";
+```
+
+`Klaim` is the exported runtime object that receives APIs, groups, and route functions as you register them.
+
+## Signature
+
+```typescript
+export const Klaim: IApiReference = {};
+```
+
+Supporting exported types from the same source file:
+
+```typescript
+export type IArgs = Record<string, unknown>;
+export type IBody = Record<string, unknown>;
+```
+
+Internally, route handlers are created with these shapes:
+
+```typescript
+type RouteFunction<T = any> = {
+  (offset?: number, args?: IArgs, body?: IBody): Promise<T>;
+};
+```
+
+That `RouteFunction` type is not exported from the package root, but it explains how generated route functions behave.
+
+## How Calls Work
+
+For non-paginated routes:
+
+```typescript
+await Klaim.api.route<T>(args?, body?);
+```
+
+For paginated routes:
+
+```typescript
+await Klaim.api.route<T>(offset?, args?, body?);
+```
+
+`createRouteHandler()` decides which call form to use by checking `element.pagination`.
+
+## Common Patterns
+
+### Basic route call
+
+```typescript
+Api.create("todos", "https://jsonplaceholder.typicode.com", () => {
+  Route.get("getOne", "/todos/[id]");
+});
+
+const todo = await Klaim.todos.getOne({ id: 1 });
+```
+
+### Route call with body
+
+```typescript
+Api.create("posts", "https://jsonplaceholder.typicode.com", () => {
+  Route.post("create", "/posts");
+});
+
+const created = await Klaim.posts.create(
+  {},
+  { title: "Hello", body: "From Klaim", userId: 1 }
+);
+```
+
+### Paginated route call
+
+```typescript
+Api.create("pokemon", "https://pokeapi.co/api/v2", () => {
+  Route.get("list", "/pokemon").withPagination({
+    pageParam: "offset",
+    limitParam: "limit",
+    limit: 5,
+  });
+});
+
+const firstPage = await Klaim.pokemon.list(0);
+const secondPage = await Klaim.pokemon.list(5);
+```
+
+## Notes on Dynamic Structure
+
+`Klaim` starts as an empty object. `Registry.registerElement()` adds nested objects for APIs and groups, and `Registry.addToKlaimRoute()` writes route functions into the correct nested location.
+
+That means:
+
+- The object shape is determined entirely by registration order and names.
+- `Registry.reset()` can clear the object back to empty.
+- Property names are normalized to camelCase during registration.
+
+Related pages: [Registry](/docs/api-reference/registry), [Request Lifecycle](/docs/request-lifecycle), [Api](/docs/api-reference/api)

package/docs/codedocs/api-reference/registry.md

@@ -0,0 +1,109 @@
+---
+title: "Registry"
+description: "Reference for the exported `Registry` singleton that stores Klaim declarations and builds the runtime tree."
+---
+
+Source: `src/core/Registry.ts`
+
+Import path:
+
+```typescript
+import { Registry } from "klaim";
+```
+
+`Registry` is the internal data store that keeps every API, group, and route element and mirrors that structure onto `Klaim`. It is exported, so you can use it in tests, debugging tools, or advanced runtime extensions.
+
+## Signatures
+
+```typescript
+class Registry {
+  static get i(): Registry;
+
+  registerElement(element: IElement): void;
+  getCurrentParent(): IElement | null;
+  setCurrentParent(fullPath: string): void;
+  clearCurrentParent(): void;
+  registerRoute(element: IElement): void;
+  getElementKey(element: IElement): string;
+  getFullPath(element: IElement): string;
+  getRoute(apiName: string, routeName: string): IElement | undefined;
+  getChildren(elementPath: string): IElement[];
+  static updateElement(element: IElement): IElement;
+  getApi(name: string): IElement | undefined;
+  reset(): void;
+}
+```
+
+## Core Methods
+
+### `Registry.i`
+
+The singleton instance getter.
+
+Example:
+
+```typescript
+const registry = Registry.i;
+```
+
+### `getRoute(apiName, routeName)`
+
+Looks up a route by its API name and route name.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `apiName` | `string` | — | API name used in the registry key. |
+| `routeName` | `string` | — | Route name used in the registry key. |
+
+Returns: `IElement | undefined`
+
+Example:
+
+```typescript
+const route = Registry.i.getRoute("inventory", "listProducts");
+```
+
+### `getApi(name)`
+
+Looks up an API by name. If the name is nested under groups, the method searches registry keys that end with `.${name}`.
+
+Returns: `IElement | undefined`
+
+### `getChildren(elementPath)`
+
+Returns every element whose `parent` exactly matches the provided path.
+
+Returns: `IElement[]`
+
+### `reset()`
+
+Clears the internal registry map and deletes every property from the exported `Klaim` object. This is mainly useful in tests.
+
+Example:
+
+```typescript
+Registry.i.reset();
+```
+
+## Registration Methods
+
+`registerElement()` is used for APIs and groups. `registerRoute()` is used for routes and throws if no current parent is set. These methods are usually called by `Api.create()`, `Group.create()`, and `Route.*()` for you.
+
+Example:
+
+```typescript
+Api.create("service", "https://example.com", () => {
+  Route.get("health", "/health");
+});
+
+console.log(Registry.i.getRoute("service", "health"));
+```
+
+## When to Use the Registry Directly
+
+- Inspect declarations in tests
+- Attach callbacks after registration
+- Clear global state between isolated runs
+- Build custom debug tooling around registered elements
+
+Related pages: [Klaim Runtime](/docs/api-reference/klaim), [Hook](/docs/api-reference/hook), [Types](/docs/types)

package/docs/codedocs/api-reference/route.md

@@ -0,0 +1,165 @@
+---
+title: "Route"
+description: "Reference for the exported `Route` class, HTTP helpers, and validation support."
+---
+
+Source: `src/core/Route.ts`
+
+Import path:
+
+```typescript
+import { Route } from "klaim";
+```
+
+`Route` defines one endpoint inside an API or group context. It carries the HTTP method, path, header overrides, detected path arguments, and optional runtime controls such as validation, retry, and timeout.
+
+## Signatures
+
+```typescript
+class Route extends Element {
+  constructor(
+    name: string,
+    url: string,
+    headers: IHeaders = {},
+    method: RouteMethod = RouteMethod.GET
+  );
+
+  static get(name: string, url: string, headers: IHeaders = {}): Element;
+  static post(name: string, url: string, headers: IHeaders = {}): Element;
+  static put(name: string, url: string, headers: IHeaders = {}): Element;
+  static delete(name: string, url: string, headers: IHeaders = {}): Element;
+  static patch(name: string, url: string, headers: IHeaders = {}): Element;
+  static options(name: string, url: string, headers: IHeaders = {}): Element;
+
+  validate(schema: { validate: (data: unknown) => Promise<unknown> }): Element;
+}
+```
+
+Inherited chainable methods:
+
+```typescript
+before(callback: ICallback<ICallbackBeforeArgs>): this
+after(callback: ICallback<ICallbackAfterArgs>): this
+onCall(callback: ICallback<ICallbackCallArgs>): this
+withCache(duration: number = 20): this
+withRetry(maxRetries: number = 2): this
+withPagination(config: IPaginationConfig = {}): this
+withRate(config: Partial<IRateLimitConfig> = {}): this
+withTimeout(duration: number = 5, message: string = "Request timed out"): this
+```
+
+## Constructor
+
+Most users should prefer the static helpers because they register routes automatically, but the public constructor exists.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `name` | `string` | — | Route name, normalized to camelCase by `Element`. |
+| `url` | `string` | — | Route path fragment, scanned for `[param]` placeholders. |
+| `headers` | `Record<string, string>` | `{}` | Route-level header overrides. |
+| `method` | `RouteMethod` | `GET` | HTTP method stored on the route element. |
+
+Returns: `Route`
+
+## Static Route Helpers
+
+All six helpers call the same private `createRoute()` function and differ only by the HTTP method they assign.
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `get` | `Route.get(name, url, headers?)` | Register a GET route. |
+| `post` | `Route.post(name, url, headers?)` | Register a POST route. |
+| `put` | `Route.put(name, url, headers?)` | Register a PUT route. |
+| `delete` | `Route.delete(name, url, headers?)` | Register a DELETE route. |
+| `patch` | `Route.patch(name, url, headers?)` | Register a PATCH route. |
+| `options` | `Route.options(name, url, headers?)` | Register an OPTIONS route. |
+
+Example:
+
+```typescript
+Api.create("users", "https://example.com", () => {
+  Route.get("list", "/users");
+  Route.get("getOne", "/users/[id]");
+  Route.post("create", "/users", { Authorization: "Bearer token" });
+});
+```
+
+## `validate(schema)`
+
+Adds a response validator. The schema object only needs a `validate()` method that returns a promise, which is why Yup works out of the box in the tests.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `schema` | `{ validate: (data: unknown) => Promise<unknown> }` | — | Async validation or coercion schema. |
+
+Returns: `Element`
+
+Example:
+
+```typescript
+import * as yup from "yup";
+
+const schema = yup.object({
+  id: yup.number().required(),
+  title: yup.string().required(),
+});
+
+Api.create("posts", "https://jsonplaceholder.typicode.com", () => {
+  Route.get("getOne", "/posts/[id]").validate(schema);
+});
+```
+
+## Runtime Controls
+
+### `before(callback)` and `after(callback)`
+
+These hooks are executed directly by `applyBefore()` and `applyAfter()` in `src/core/Klaim.ts`.
+
+Example:
+
+```typescript
+Route.get("profile", "/me").before(({ route, api, url, config }) => {
+  return {
+    route,
+    api,
+    url,
+    config: {
+      ...config,
+      headers: {
+        ...(config.headers as Record<string, string>),
+        Authorization: `Bearer ${token}`,
+      },
+    },
+  };
+});
+```
+
+### `withPagination(config?)`
+
+Marks the route as paginated. The generated route handler then expects the first argument to be the page or offset number.
+
+Example:
+
+```typescript
+Route.get("list", "/pokemon").withPagination({
+  pageParam: "offset",
+  limitParam: "limit",
+  limit: 20,
+});
+```
+
+### `withRate(config?)`, `withRetry(maxRetries?)`, `withTimeout(duration?, message?)`, `withCache(duration?)`
+
+These settings are enforced inside `fetchWithRetry()` and `fetchWithCache()`.
+
+Example:
+
+```typescript
+Route.get("expensive", "/reports/[id]")
+  .withRate({ limit: 2, duration: 60 })
+  .withRetry(1)
+  .withTimeout(5)
+  .withCache(120);
+```
+
+Related pages: [Api](/docs/api-reference/api), [Klaim Runtime](/docs/api-reference/klaim), [Types](/docs/types)

package/docs/codedocs/architecture.md

@@ -0,0 +1,129 @@
+---
+title: "Architecture"
+description: "Understand how Klaim registers APIs, builds the runtime object, and executes requests."
+---
+
+Klaim is built around a small set of runtime primitives: `Element` for shared configuration, `Api` and `Route` for declaration, `Group` for hierarchy, `Registry` for storage, and `Klaim` for execution. The codebase is compact, and almost all user-facing behavior flows through `src/core/Klaim.ts` and `src/core/Registry.ts`.
+
+```mermaid
+graph TD
+  A[Api.create / Group.create / Route.get] --> B[Element instances]
+  B --> C[Registry registerElement/registerRoute]
+  C --> D[Klaim object tree]
+  D --> E[createRouteHandler]
+  E --> F[callApi]
+  F --> G[applyArgs]
+  F --> H[applyBefore]
+  F --> I[fetchWithRetry]
+  I --> J[rateLimit.ts]
+  I --> K[fetchWithCache.ts]
+  I --> L[timeout.ts]
+  F --> M[schema.validate]
+  F --> N[applyAfter]
+  F --> O[Hook.run]
+```
+
+## Module Roles
+
+`src/core/Element.ts` is the common base class. It owns the shared state for all declared elements: `name`, `url`, `headers`, callback slots, cache settings, retry settings, rate limiting, timeout, pagination, and validation metadata. Every other core class inherits these chainable configuration methods from `Element`.
+
+`src/core/Api.ts` and `src/core/Route.ts` are declaration helpers. `Api.create()` creates an API node and temporarily changes the current parent in the registry so route declarations inside its callback register under that API. `Route.get()`, `Route.post()`, and the other static helpers create route nodes and register them under the current parent.
+
+`src/core/Group.ts` adds hierarchy. A group can sit above APIs or above routes, depending on where it is declared. After `Group.create()` finishes its callback, group-level `withCache()`, `withRetry()`, `withTimeout()`, `before()`, `after()`, and `onCall()` copy settings down to already-registered children.
+
+`src/core/Registry.ts` is the structural center of the library. It stores every element in `_elements`, tracks the current declaration parent in `_currentParent`, and mutates the exported `Klaim` object so that each route becomes a callable function at the correct nested property path.
+
+`src/core/Klaim.ts` is the runtime center. `createRouteHandler()` builds the public callable functions placed on the `Klaim` object. `callApi()` resolves the owning API, fills route arguments, adds pagination query parameters when configured, applies middleware, executes the request with retry and timeout handling, validates the response, and then fires hook callbacks.
+
+## Key Design Decisions
+
+### Declarations are runtime-driven, not generated
+
+Klaim does not generate a client from an OpenAPI schema or compile route definitions into files. Instead, it builds the client in memory by mutating the exported `Klaim` object at registration time. You can see this in `Registry.registerElement()` and `Registry.addToKlaimRoute()` inside `src/core/Registry.ts`.
+
+Why this choice matters:
+
+- You can declare APIs dynamically from normal application code.
+- Nested groups are just nested object paths, so the runtime shape is easy to inspect.
+- The trade-off is that type inference is limited compared with code generation, because the object shape is created at runtime.
+
+### Configuration lives on elements
+
+The `Element` base class in `src/core/Element.ts` keeps configuration local to each API, route, or group. That makes chainable declarations easy:
+
+```typescript
+Route.get("list", "/users")
+  .withRetry(3)
+  .withTimeout(2)
+  .withRate({ limit: 10, duration: 60 });
+```
+
+This design keeps the public API small, but it also means the runtime has to decide which level wins when both API and route settings exist. In `fetchWithRetry()`, route-level retry, timeout, and rate limit take precedence; API-level values are fallback values.
+
+### The middleware model is single-slot, not a chain
+
+`Element.callbacks` stores one `before`, one `after`, and one `call` callback. There is no internal array and no middleware composition pipeline. `callApi()` invokes `route.callbacks.before` and `route.callbacks.after`; `fetchWithRetry()` invokes `route.callbacks.call` or, if it is missing, `api.callbacks.call`.
+
+Why this is important:
+
+- The behavior is predictable and cheap.
+- Overwriting a callback is easy to reason about.
+- You cannot register multiple `before` handlers for the same route and expect them all to run.
+
+## Request Lifecycle
+
+```mermaid
+sequenceDiagram
+  participant U as User Code
+  participant K as Klaim route handler
+  participant R as Registry
+  participant F as callApi/fetchWithRetry
+  participant N as Network
+  U->>K: Klaim.api.route(args, body)
+  K->>F: callApi(parent, route, ...)
+  F->>R: getApi(...)
+  F->>F: applyArgs + pagination
+  F->>F: route before callback
+  F->>F: rate limit / retry / timeout
+  F->>N: fetch(...)
+  N-->>F: JSON response
+  F->>F: schema.validate(...)
+  F->>F: route after callback
+  F->>F: Hook.run("api.route")
+  F-->>U: parsed data
+```
+
+The lifecycle is deliberately linear:
+
+1. Resolve the API owner for the route.
+2. Build the final URL from `api.url` and `route.url`.
+3. Replace `[param]` placeholders with values from `args`.
+4. Add pagination query parameters if `route.pagination` is defined.
+5. Build the fetch config with merged headers and a JSON body for non-GET requests.
+6. Run the route-level `before` callback if present.
+7. Execute the request through `fetchWithRetry()`, which also handles rate limits and timeouts.
+8. Run schema validation if `route.schema` exists.
+9. Run the route-level `after` callback if present.
+10. Trigger `Hook.run()` for the route name.
+
+## How the Pieces Fit Together
+
+The usual declaration flow is:
+
+1. `Api.create("service", "...", () => { ... })`
+2. `Registry.setCurrentParent("service")`
+3. `Route.get("list", "/items")`
+4. `Registry.registerRoute(route)`
+5. `Registry.addToKlaimRoute(route)`
+6. `Klaim.service.list()` becomes callable
+
+Groups introduce one extra parent path layer, but the principle stays the same. The registry always stores a dot-path such as `shop.catalog.products.list`, and the `Klaim` object mirrors that structure.
+
+Important implementation details to keep in mind while reading the rest of the docs:
+
+- Names are normalized with `toCamelCase()` from `src/tools/toCamelCase.ts`.
+- URLs are normalized with `cleanUrl()` from `src/tools/cleanUrl.ts`, which trims only leading and trailing slashes.
+- Cache storage is global and in-memory through the `Cache` singleton in `src/core/Cache.ts`.
+- Rate limiting is global and in-memory through the `requestLogs` map in `src/tools/rateLimit.ts`.
+
+From here, the most useful next pages are [APIs and Routes](/docs/api-and-routes), [Groups and Hierarchy](/docs/groups-and-hierarchy), and [Request Lifecycle](/docs/request-lifecycle).

package/docs/codedocs/groups-and-hierarchy.md

@@ -0,0 +1,110 @@
+---
+title: "Groups and Hierarchy"
+description: "See how Klaim groups APIs and routes into nested namespaces with inherited settings."
+---
+
+Groups are Klaim’s namespace and inheritance mechanism. They let you organize routes inside an API, organize multiple APIs under a shared namespace, and apply some settings to all children after registration.
+
+## What a Group Is
+
+A `Group` is an `Element` with `type: "group"` created by `Group.create()` in `src/core/Group.ts`. Unlike an API, it has no real base URL. Its job is structural:
+
+- When declared inside an API callback, it creates a nested route namespace.
+- When declared at the root level, it can hold multiple APIs.
+- When declared inside another group, it creates deeper nesting.
+
+Because `Registry.registerElement()` treats groups the same way it treats APIs for object creation, both appear as nested objects on `Klaim`.
+
+## Why Groups Exist
+
+Groups solve two practical problems:
+
+- Large API surfaces become navigable because related routes live under one subtree.
+- Shared behavior such as retries, timeout, or a request hook can be copied to all children in one place.
+
+This is especially useful when a service has feature areas with different runtime needs, such as long-lived cached catalog routes and short-timeout admin routes.
+
+## How Groups Work Internally
+
+`Group.create()` in `src/core/Group.ts` computes a dot-path using the current parent, registers the group in the registry, switches the current parent to the new group path, runs the callback, and then restores the previous parent. That means every route or API declared inside the callback receives a parent path that includes the group.
+
+After the callback, chainable methods such as `withCache()` and `before()` iterate through `Registry.i.getChildren(Registry.i.getFullPath(this))` and copy settings to children that do not already define their own values.
+
+```mermaid
+graph TD
+  A[Group.create shop] --> B[register group]
+  B --> C[setCurrentParent shop]
+  C --> D[Api.create catalog]
+  C --> E[Group.create admin]
+  E --> F[Route.get list]
+  E --> G[Route.post create]
+  B --> H[withRetry or before propagates to children]
+```
+
+That propagation model explains an important behavior: group settings affect the elements created during the callback because the group methods run after registration is complete.
+
+## Basic Usage
+
+This example groups related routes under one API:
+
+```typescript
+import { Api, Group, Klaim, Route } from "klaim";
+
+Api.create("store", "https://dummyjson.com", () => {
+  Group.create("products", () => {
+    Route.get("list", "/products");
+    Route.get("getOne", "/products/[id]");
+  }).withCache(60);
+});
+
+const products = await Klaim.store.products.list();
+const phone = await Klaim.store.products.getOne({ id: 1 });
+```
+
+## Advanced Usage
+
+This example groups multiple APIs at the root and gives them a shared timeout and route hook through the group.
+
+```typescript
+import { Api, Group, Hook, Klaim, Route } from "klaim";
+
+Group.create("services", () => {
+  Api.create("auth", "https://example.com/auth", () => {
+    Route.post("login", "/login");
+  });
+
+  Api.create("billing", "https://example.com/billing", () => {
+    Route.get("invoices", "/invoices");
+  });
+})
+  .withTimeout(2, "Shared service timeout")
+  .onCall(() => {
+    console.log("A grouped service route is being called");
+  });
+
+Hook.subscribe("auth.login", () => {
+  console.log("login completed");
+});
+
+await Klaim.services.auth.login({}, { email: "a@example.com", password: "secret" });
+await Klaim.services.billing.invoices();
+```
+
+## Relationship to APIs and the Registry
+
+Groups do not execute requests themselves. They exist to change the parent path that `Registry` uses and to copy configuration into children. APIs still provide the base URL. Routes still provide the HTTP method and path. The final call target always remains a route function attached somewhere under `Klaim`.
+
+Because `Registry.getApi()` searches upward through the dot-path, nested routes can still find their owning API even when they live several group levels below it.
+
+<Callout type="warn">`Group` inherits `withRate()` and `withPagination()` from `Element`, but `src/core/Group.ts` does not propagate those settings and `src/core/Klaim.ts` only reads rate limits from APIs and routes and pagination from routes. In other words, route groups are a good fit for cache, retry, timeout, and callbacks, but not for shared pagination or shared rate limiting in the current implementation.</Callout>
+
+<Accordions>
+<Accordion title="Why use groups instead of flat route names?">
+Flat route names scale poorly once an API has more than a dozen operations because semantic boundaries disappear. A grouped tree such as `Klaim.store.products.list()` expresses intent more clearly than `Klaim.storeListProducts()`, and the registry already stores dot-paths internally, so the grouping model is cheap to maintain. The trade-off is that dynamic object traversal becomes deeper, which can make ad hoc introspection slightly more awkward. For most real integrations, the readability gain is worth that extra nesting.
+</Accordion>
+<Accordion title="What are the limits of group-level inheritance?">
+Group inheritance is copy-based, not live composition. When you call `.withCache()` or `.before()` on a group, `src/core/Group.ts` walks the already-created children and fills in missing values, but it does not keep a stack of inherited middleware or recompute descendants later. That makes the implementation simple and avoids complicated merge logic, but it also means one child callback can replace another instead of forming a pipeline. If you need truly layered middleware semantics, you have to model them yourself inside one callback function.
+</Accordion>
+</Accordions>
+
+The next useful page is [Request Lifecycle](/docs/request-lifecycle), which shows what happens after a grouped route is actually invoked.