klaim 1.12.48 → 1.12.49

package/context7.json

@@ -0,0 +1,4 @@
+{
+  "url": "https://context7.com/antharuu/klaim",
+  "public_key": "pk_uReHomekMKo4V8j7PQ2Xi"
+}

package/deno.json

@@ -1,6 +1,6 @@
 {
     "name": "@antharuu/klaim",
-    "version": "1.12.48",
+    "version": "1.12.49",
     "description": "Klaim is a lightweight TypeScript library designed to manage APIs and record requests, optimized for an optimal user experience.",
     "repository": {
         "type": "git",

package/docs/codedocs/api-and-routes.md

@@ -0,0 +1,120 @@
+---
+title: "APIs and Routes"
+description: "Learn how Klaim turns API declarations and route definitions into callable runtime functions."
+---
+
+APIs and routes are the core abstraction in Klaim. An API defines a base URL and shared defaults. A route defines an HTTP method, a path fragment, optional headers, and optional route-specific behavior. Together they become functions on the exported `Klaim` object.
+
+## What This Concept Solves
+
+Without a declaration layer, most apps end up with a pile of small wrappers around `fetch()` that disagree on URL formatting, headers, and error behavior. Klaim centralizes that setup:
+
+- `Api.create()` defines the host and top-level namespace.
+- `Route.get()`, `Route.post()`, and the other static helpers define endpoints.
+- `Registry` converts those definitions into callable functions.
+
+The result is a runtime shape that matches how people think about an integration: `Klaim.github.repos.list`, not `"GET /repos"` buried in a helper string.
+
+## How It Relates to Other Concepts
+
+- [Groups and Hierarchy](/docs/groups-and-hierarchy) add nesting above or below APIs.
+- [Request Lifecycle](/docs/request-lifecycle) explains what happens once you call a route.
+- [Resilience and Control](/docs/resilience-and-control) covers the chainable settings inherited from `Element`.
+
+## How It Works Internally
+
+`Api.create()` in `src/core/Api.ts` does four important things:
+
+1. Normalizes the API name with `toCamelCase()`.
+2. Creates an `Api` instance that inherits from `Element`.
+3. Registers that instance in `Registry.i.registerElement(api)`.
+4. Sets the API as the current parent so routes defined in the callback register under it.
+
+`Route.get()` and the other static helpers in `src/core/Route.ts` all delegate to `createRoute()`. That helper creates a `Route` instance, records its HTTP method, and calls `detectArguments()` to scan the path for bracket parameters like `[id]`.
+
+When `Registry.registerRoute()` runs in `src/core/Registry.ts`, the route gets a `parent` path and is immediately added to the `Klaim` object by `addToKlaimRoute()`. That method uses `createRouteHandler()` from `src/core/Klaim.ts` so the route becomes a function instead of a plain object.
+
+```mermaid
+flowchart TD
+  A[Api.create] --> B[registerElement api]
+  B --> C[setCurrentParent api]
+  C --> D[Route.get or Route.post]
+  D --> E[detectArguments]
+  E --> F[registerRoute]
+  F --> G[addToKlaimRoute]
+  G --> H[Klaim.api.route = function]
+```
+
+Two details are easy to miss:
+
+- Path arguments are required only when the route path contains `[name]` segments.
+- Pagination changes the call signature. If `withPagination()` has been set on a route, the first argument becomes the page or offset value.
+
+## Basic Usage
+
+```typescript
+import { Api, Klaim, Route } from "klaim";
+
+type User = {
+  id: number;
+  name: string;
+};
+
+Api.create("usersApi", "https://jsonplaceholder.typicode.com", () => {
+  Route.get("listUsers", "/users");
+  Route.get("getUser", "/users/[id]");
+});
+
+const users = await Klaim.usersApi.listUsers<User[]>();
+const one = await Klaim.usersApi.getUser<User>({ id: 1 });
+```
+
+## Advanced Usage
+
+This example combines route headers, a request body, and response validation on a non-GET route.
+
+```typescript
+import { Api, Klaim, Route } from "klaim";
+import * as yup from "yup";
+
+type PostInput = {
+  title: string;
+  body: string;
+  userId: number;
+};
+
+type PostResponse = PostInput & {
+  id: number;
+};
+
+const postSchema = yup.object({
+  id: yup.number().required(),
+  title: yup.string().required(),
+  body: yup.string().required(),
+  userId: yup.number().required(),
+});
+
+Api.create("posts", "https://jsonplaceholder.typicode.com", () => {
+  Route.post("create", "/posts", {
+    Authorization: "Bearer example-token",
+  }).validate(postSchema);
+});
+
+const created = await Klaim.posts.create<PostResponse>(
+  {},
+  { title: "Hello", body: "Created with Klaim", userId: 1 }
+);
+```
+
+<Callout type="warn">Route names and API names are always normalized with `toCamelCase()` from `src/tools/toCamelCase.ts`. If you declare `Route.get("get-user", "/users/[id]")`, the runtime property will be `Klaim.api.getUser`, not `get-user`. Missing `[id]` arguments throw `MissingArgumentError` before any network request is made.</Callout>
+
+<Accordions>
+<Accordion title="Why use declarative routes instead of hand-written fetch helpers?">
+Klaim’s declaration model gives you a single source of truth for the base URL, route path, HTTP method, and runtime behavior. That makes it easy to audit what an integration does because the registration code mirrors the final runtime object. In `src/core/Registry.ts`, route declarations are converted directly into functions on `Klaim`, so the runtime stays close to the source. The trade-off is that type inference is weaker than a generated client because the object graph is created dynamically at runtime, not inferred from static declarations.
+</Accordion>
+<Accordion title="Why do route helpers return `Element` instead of a narrower route-specific type?">
+The static route helpers in `src/core/Route.ts` return `Element`, which keeps the chaining surface consistent with `Api` and `Group`. That makes calls like `.withRetry()`, `.withTimeout()`, and `.before()` available from one shared base class. The cost is that route-specific methods such as `validate()` are only visible when you work with a `Route` instance directly rather than through the static return type. In practice, users usually chain `validate()` immediately on the static call site, and TypeScript still resolves it from the concrete class instance.
+</Accordion>
+</Accordions>
+
+For full signatures, see [API](/docs/api-reference/api), [Route](/docs/api-reference/route), and [Klaim Runtime](/docs/api-reference/klaim).

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

@@ -0,0 +1,143 @@
+---
+title: "Api"
+description: "Reference for the exported `Api` class and its chainable configuration methods."
+---
+
+Source: `src/core/Api.ts`
+
+Import path:
+
+```typescript
+import { Api } from "klaim";
+```
+
+`Api` represents a top-level service definition. You do not instantiate it directly; the public entrypoint is the static `Api.create()` method.
+
+## Signatures
+
+```typescript
+class Api extends Element {
+  static create(
+    name: string,
+    url: string,
+    callback: IApiCallback,
+    headers: IHeaders = {}
+  ): Element;
+}
+```
+
+Inherited chainable methods from `Element`:
+
+```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
+```
+
+## `Api.create()`
+
+Creates, registers, and scopes an API declaration. Internally, `src/core/Api.ts` stores the current parent from `Registry`, registers the new API, sets it as the active parent while your callback runs, and restores the previous context afterward.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `name` | `string` | — | API name. It is normalized to camelCase before registration. |
+| `url` | `string` | — | Base URL for the API. Leading and trailing slashes are trimmed. |
+| `callback` | `() => void` | — | Declaration callback used to register routes or nested groups. |
+| `headers` | `Record<string, string>` | `{}` | Default headers merged into every route call under the API. |
+
+Returns: `Element`
+
+Example:
+
+```typescript
+import { Api, Route } from "klaim";
+
+Api.create("billing-api", "https://api.example.com", () => {
+  Route.get("listInvoices", "/invoices");
+});
+```
+
+## Chainable Methods
+
+### `withCache(duration?: number)`
+
+Enables response caching for routes under the API. Runtime enforcement happens in `fetchWithRetry()` inside `src/core/Klaim.ts`.
+
+Example:
+
+```typescript
+Api.create("catalog", "https://dummyjson.com", () => {
+  Route.get("listProducts", "/products");
+}).withCache(60);
+```
+
+### `withRetry(maxRetries?: number)`
+
+Sets the API-level retry fallback used when a route does not define its own retry count.
+
+Example:
+
+```typescript
+Api.create("search", "https://api.example.com", () => {
+  Route.get("query", "/search");
+}).withRetry(3);
+```
+
+### `withRate(config?: Partial<IRateLimitConfig>)`
+
+Sets the API-level rate limit budget. `src/core/Klaim.ts` uses this when the route does not define its own rate config.
+
+Example:
+
+```typescript
+Api.create("github", "https://api.github.com", () => {
+  Route.get("repos", "/users/[user]/repos");
+}).withRate({ limit: 10, duration: 60 });
+```
+
+### `withTimeout(duration?: number, message?: string)`
+
+Sets the API-level timeout fallback.
+
+Example:
+
+```typescript
+Api.create("slowService", "https://example.com", () => {
+  Route.get("data", "/data");
+}).withTimeout(2, "Service request timed out");
+```
+
+### `onCall(callback)`
+
+Sets the API-level `onCall` callback. `fetchWithRetry()` uses it only when the route does not define its own `onCall`.
+
+Example:
+
+```typescript
+Api.create("metrics", "https://example.com", () => {
+  Route.get("overview", "/overview");
+}).onCall(() => {
+  console.log("a metrics route call started");
+});
+```
+
+### `before(callback)` and `after(callback)`
+
+These methods exist because `Api` inherits them from `Element`, but `callApi()` currently reads only route-level `before` and `after` callbacks. Use them only if you are also copying them to routes yourself or applying them through a group.
+
+Example:
+
+```typescript
+const api = Api.create("users", "https://example.com", () => {
+  Route.get("list", "/users");
+});
+
+api.before(({ route, api, url, config }) => ({ route, api, url, config }));
+```
+
+Related pages: [Route](/docs/api-reference/route), [Group](/docs/api-reference/group), [Klaim Runtime](/docs/api-reference/klaim)

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

@@ -0,0 +1,84 @@
+---
+title: "Cache"
+description: "Reference for the exported in-memory `Cache` singleton used by Klaim's cached fetch path."
+---
+
+Source: `src/core/Cache.ts`
+
+Import path:
+
+```typescript
+import { Cache } from "klaim";
+```
+
+`Cache` is a singleton in-memory store with TTL expiration and LRU-style eviction. Klaim uses it through `src/tools/fetchWithCache.ts` when caching is enabled.
+
+## Signatures
+
+```typescript
+class Cache {
+  static get i(): Cache;
+  set(key: string, value: unknown, ttl: number = 0): void;
+  has(key: string): boolean;
+  get(key: string): unknown | null;
+  clear(): void;
+  get size(): number;
+}
+```
+
+## Methods
+
+### `Cache.i`
+
+Returns the singleton cache instance.
+
+### `set(key, value, ttl?)`
+
+Stores a value in the cache. A `ttl` of `0` means the cache entry does not expire.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `key` | `string` | — | Cache key. Klaim derives this from URL plus fetch config. |
+| `value` | `unknown` | — | Value to store. |
+| `ttl` | `number` | `0` | Time to live in milliseconds. |
+
+Example:
+
+```typescript
+Cache.i.set("user:1", { id: 1, name: "Ada" }, 60_000);
+```
+
+### `has(key)`
+
+Checks whether a non-expired cache entry exists. Expired entries are removed on access.
+
+### `get(key)`
+
+Returns cached data or `null`. When an entry is returned, the underlying map entry is moved to the end to behave like an LRU cache.
+
+### `clear()`
+
+Removes every cached entry.
+
+### `size`
+
+Returns the current number of entries stored in memory.
+
+## Example With Klaim
+
+```typescript
+Api.create("catalog", "https://dummyjson.com", () => {
+  Route.get("listProducts", "/products");
+}).withCache(60);
+
+await Klaim.catalog.listProducts();
+console.log(Cache.i.size);
+```
+
+## Implementation Notes
+
+`src/tools/fetchWithCache.ts` computes a cache key by hashing `input.toString()` plus `JSON.stringify(init)` with the helper from `src/tools/hashStr.ts`. That means two otherwise identical requests with different headers or bodies will get different cache entries, which is usually the right behavior for HTTP client caching inside an application process.
+
+The cache is process-local and memory-backed. It is useful for reducing duplicate requests inside one runtime, but it is not a distributed cache and it is not persisted across restarts. If you need cross-process consistency, you should treat Klaim’s cache as a local optimization layer and keep the authoritative cache somewhere else.
+
+Related pages: [Resilience and Control](/docs/resilience-and-control), [Api](/docs/api-reference/api), [Route](/docs/api-reference/route)

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

@@ -0,0 +1,113 @@
+---
+title: "Errors"
+description: "Reference for the exported Klaim-specific error classes."
+---
+
+Source: `src/core/errors.ts`
+
+Import path:
+
+```typescript
+import {
+  InvalidPathError,
+  KlaimError,
+  MissingArgumentError,
+  RateLimitError,
+  RetryExhaustedError,
+  TimeoutError,
+} from "klaim";
+```
+
+Klaim exports a small error hierarchy so callers can catch specific operational failures.
+
+## Signatures
+
+```typescript
+class KlaimError extends Error {
+  constructor(message: string);
+}
+
+class RateLimitError extends KlaimError {
+  readonly retryAfterMs: number;
+  constructor(message: string, retryAfterMs: number);
+}
+
+class TimeoutError extends KlaimError {
+  constructor(message: string);
+}
+
+class RetryExhaustedError extends KlaimError {
+  readonly attempts: number;
+  readonly cause: Error | undefined;
+  constructor(message: string, attempts: number, cause?: Error);
+}
+
+class MissingArgumentError extends KlaimError {
+  readonly argument: string;
+  constructor(argument: string);
+}
+
+class InvalidPathError extends KlaimError {
+  constructor(path: string);
+}
+```
+
+## Error Classes
+
+### `KlaimError`
+
+Base class for every library-specific error.
+
+### `RateLimitError`
+
+Thrown by `fetchWithRetry()` when `checkRateLimit()` denies a request. The `retryAfterMs` property tells you when the next request should be allowed.
+
+### `TimeoutError`
+
+Thrown by `withTimeout()` from `src/tools/timeout.ts` when the configured duration expires before the request completes.
+
+### `RetryExhaustedError`
+
+Thrown by `fetchWithRetry()` after all attempts have failed. `attempts` contains the final attempt count and `cause` stores the last underlying error when available.
+
+### `MissingArgumentError`
+
+Thrown by `applyArgs()` when a route path contains a required `[param]` but the caller did not supply it in `args`.
+
+### `InvalidPathError`
+
+Thrown by `callApi()` when it cannot resolve a valid route and owning API combination for the requested path.
+
+## Example
+
+```typescript
+try {
+  await Klaim.pokemon.list(0);
+} catch (error) {
+  if (error instanceof MissingArgumentError) {
+    console.error(error.argument);
+  }
+
+  if (error instanceof RateLimitError) {
+    console.error(error.retryAfterMs);
+  }
+}
+```
+
+## Practical Guidance
+
+These error classes are most useful when you let Klaim’s runtime controls do the work and then branch on the result. For example, `TimeoutError` and `RateLimitError` are usually recoverable at the UI or job-runner layer, while `InvalidPathError` and `MissingArgumentError` usually indicate a programming mistake that should be fixed rather than retried. `RetryExhaustedError` sits between those two categories because it wraps an operational failure but also preserves the final underlying `cause`.
+
+Because every custom error extends `KlaimError`, you can also catch the whole family when you want library-specific fallback behavior:
+
+```typescript
+try {
+  await Klaim.inventory.listProducts();
+} catch (error) {
+  if (error instanceof KlaimError) {
+    console.error("klaim runtime failure", error.message);
+  }
+}
+```
+
+Related pages: [Resilience and Control](/docs/resilience-and-control), [Klaim Runtime](/docs/api-reference/klaim)

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

@@ -0,0 +1,107 @@
+---
+title: "Group"
+description: "Reference for the exported `Group` class and its propagation-based configuration helpers."
+---
+
+Source: `src/core/Group.ts`
+
+Import path:
+
+```typescript
+import { Group } from "klaim";
+```
+
+`Group` creates a namespace layer in the registry and, for some settings, copies configuration into already-registered children.
+
+## Signatures
+
+```typescript
+class Group extends Element {
+  static create(name: string, callback: () => void): Element;
+
+  withCache(duration = 20): this;
+  withRetry(maxRetries = 2): this;
+  withTimeout(duration = 5, message = "Request timed out"): this;
+  before(callback: ICallback<ICallbackBeforeArgs>): this;
+  after(callback: ICallback<ICallbackAfterArgs>): this;
+  onCall(callback: ICallback<ICallbackCallArgs>): this;
+}
+```
+
+Inherited but not overridden:
+
+```typescript
+withPagination(config: IPaginationConfig = {}): this
+withRate(config: Partial<IRateLimitConfig> = {}): this
+```
+
+## `Group.create()`
+
+Registers a group under the current parent and executes your callback inside that namespace.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `name` | `string` | — | Group name, normalized to camelCase. |
+| `callback` | `() => void` | — | Declaration callback for nested APIs, groups, or routes. |
+
+Returns: `Element`
+
+Example:
+
+```typescript
+Api.create("shop", "https://dummyjson.com", () => {
+  Group.create("products", () => {
+    Route.get("list", "/products");
+  });
+});
+```
+
+## Propagating Methods
+
+### `withCache(duration?)`
+
+Copies cache settings to children that do not already define a cache value.
+
+### `withRetry(maxRetries?)`
+
+Copies retry settings to children that do not already define retry.
+
+### `withTimeout(duration?, message?)`
+
+Copies timeout settings to children that do not already define timeout.
+
+### `before(callback)`, `after(callback)`, `onCall(callback)`
+
+Copies callbacks to children that do not already define those callback slots.
+
+Example:
+
+```typescript
+Api.create("shop", "https://dummyjson.com", () => {
+  Group.create("products", () => {
+    Route.get("list", "/products");
+    Route.get("getOne", "/products/[id]");
+  })
+    .withRetry(2)
+    .before(({ route, api, url, config }) => ({ route, api, url, config }));
+});
+```
+
+## Inherited Methods That Need Caution
+
+`Group` inherits `withRate()` and `withPagination()` from `Element`, but `src/core/Group.ts` does not override them and `src/core/Klaim.ts` only reads route pagination plus route or API rate limits. As a result, those inherited methods do not currently have the same practical effect as the explicitly propagated methods above.
+
+Example:
+
+```typescript
+const group = Group.create("products", () => {
+  Route.get("list", "/products");
+});
+
+group.withRate({ limit: 5, duration: 10 });
+group.withPagination({ page: 1, limit: 20 });
+```
+
+The code above is valid TypeScript because the methods exist on `Element`, but the current runtime does not consume those values at the group level.
+
+Related pages: [Groups and Hierarchy](/docs/groups-and-hierarchy), [Api](/docs/api-reference/api), [Route](/docs/api-reference/route)

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

@@ -0,0 +1,78 @@
+---
+title: "Hook"
+description: "Reference for the exported `Hook` event helper used to observe completed route calls."
+---
+
+Source: `src/core/Hook.ts`
+
+Import path:
+
+```typescript
+import { Hook } from "klaim";
+```
+
+`Hook` is a simple static event registry keyed by route name. `callApi()` triggers hooks with a string shaped like ``apiName.routeName`` after a route finishes its request lifecycle.
+
+## Signatures
+
+```typescript
+class Hook {
+  static subscribe(routeName: string, callback: () => any): void;
+  static run(routeName: string): void;
+  static unsubscribe(routeName: string): void;
+  static unsubscribeAll(): void;
+}
+```
+
+## Methods
+
+### `subscribe(routeName, callback)`
+
+Registers or replaces a callback for a route key.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `routeName` | `string` | — | Route key such as `inventory.listProducts`. |
+| `callback` | `() => any` | — | Function to run when the hook is triggered. |
+
+Example:
+
+```typescript
+Hook.subscribe("inventory.listProducts", () => {
+  console.log("products loaded");
+});
+```
+
+### `run(routeName)`
+
+Executes the stored callback for a route key if one exists.
+
+### `unsubscribe(routeName)`
+
+Removes one hook callback.
+
+### `unsubscribeAll()`
+
+Clears every hook callback.
+
+## Example With Klaim
+
+```typescript
+Api.create("inventory", "https://dummyjson.com", () => {
+  Route.get("listProducts", "/products");
+});
+
+Hook.subscribe("inventory.listProducts", () => {
+  console.log("request completed");
+});
+
+await Klaim.inventory.listProducts();
+```
+
+## Operational Notes
+
+Hooks are keyed only by one string, and `subscribe()` replaces any previous callback for the same key because `_callbacks` is a `Map<string, IHookCallback>` in `src/core/Hook.ts`. This keeps the implementation small, but it also means `Hook` is not a pub-sub fan-out bus with multiple listeners per event. If you need multiple listeners, wrap them inside one callback or build a thin adapter around `Hook`.
+
+Also note the route key format used by `callApi()` in `src/core/Klaim.ts`: the runtime combines the API name and route name only. That means nested group names are not part of the hook key at execution time. A route such as `Klaim.store.products.list()` still emits `store.list`, not `store.products.list`, because the runtime does not include intermediate group segments in the hook identifier.
+
+Related pages: [Request Lifecycle](/docs/request-lifecycle), [Klaim Runtime](/docs/api-reference/klaim)