klaim 1.7.0-alpha.1 → 1.7.0-alpha.2

package/dist/klaim.es.js

@@ -8,87 +8,180 @@ function S(s) {
   return s.trim().replace(/^\/|\/$/g, "");
 }
 class y {
+  /**
+   * Creates a new element with the specified properties.
+   *
+   * @param type - Element type identifier
+   * @param name - Unique name for the element
+   * @param url - Base URL or path segment
+   * @param headers - HTTP headers for the element
+   */
   constructor(t, e, a, r = {}) {
+    /** Element type identifier */
     o(this, "type");
+    /** Element name (unique within its scope) */
     o(this, "name");
+    /** Base URL or path segment */
     o(this, "url");
+    /** HTTP headers specific to this element */
     o(this, "headers");
+    /** Reference to parent element name */
     o(this, "parent");
+    /** HTTP method (for routes) */
     o(this, "method");
+    /** Set of dynamic URL parameters */
     o(this, "arguments", /* @__PURE__ */ new Set());
+    /** Response validation schema */
     o(this, "schema");
+    /** Middleware callbacks collection */
     o(this, "callbacks", {
       before: null,
       after: null,
       call: null
     });
+    /** Cache duration in seconds, or false if disabled */
     o(this, "cache", !1);
+    /** Number of retry attempts, or false if disabled */
     o(this, "retry", !1);
     this.type = t, this.name = P(e), this.name !== e && console.warn(`Name "${e}" has been camelCased to "${this.name}"`), this.url = S(a), this.headers = r || {};
   }
+  /**
+   * Adds a before-request middleware callback.
+   *
+   * @param callback - Function to execute before the request
+   * @returns this element instance for chaining
+   */
   before(t) {
     return this.callbacks.before = t, this;
   }
+  /**
+   * Adds an after-request middleware callback.
+   *
+   * @param callback - Function to execute after the response
+   * @returns this element instance for chaining
+   */
   after(t) {
     return this.callbacks.after = t, this;
   }
+  /**
+   * Adds a request lifecycle middleware callback.
+   *
+   * @param callback - Function to execute during the request
+   * @returns this element instance for chaining
+   */
   onCall(t) {
     return this.callbacks.call = t, this;
   }
+  /**
+   * Enables response caching for this element.
+   *
+   * @param duration - Cache duration in seconds (default: 20)
+   * @returns this element instance for chaining
+   */
   withCache(t = 20) {
     return this.cache = t, this;
   }
+  /**
+   * Enables request retries for this element.
+   *
+   * @param maxRetries - Maximum number of retry attempts (default: 2)
+   * @returns this element instance for chaining
+   */
   withRetry(t = 2) {
     return this.retry = t, this;
   }
 }
 const f = class f {
   /**
-   * Private constructor to prevent instantiation from outside the class.
+   * Private constructor to enforce singleton pattern.
+   * Initializes an empty cache storage.
+   *
+   * @private
    */
   constructor() {
+    /**
+     * Internal storage for cached items.
+     * Maps keys to objects containing the data and expiration timestamp.
+     *
+     * @private
+     */
     o(this, "cache");
     this.cache = /* @__PURE__ */ new Map();
   }
   /**
-   * Provides access to the singleton instance of the class.
+   * Gets the singleton instance of the Cache.
+   * Creates the instance if it doesn't exist.
    *
-   * @returns The singleton instance of Cache.
+   * @returns The singleton Cache instance
+   * @example
+   * ```typescript
+   * const cache = Cache.i;
+   * ```
    */
   static get i() {
     return f._instance || (f._instance = new f()), f._instance;
   }
   /**
-   * Sets the cache for a specific key.
+   * Stores a value in the cache with an optional time-to-live duration.
+   *
+   * @param key - Unique identifier for the cached item
+   * @param value - The data to cache
+   * @param ttl - Time to live in milliseconds. If 0 or not provided, the item won't expire
+   * @example
+   * ```typescript
+   * // Cache a value for 5 minutes
+   * Cache.i.set("userProfile", userData, 300000);
    *
-   * @param key The key to cache the value under.
-   * @param value The value to be cached.
-   * @param ttl Time to live in milliseconds.
+   * // Cache without expiration
+   * Cache.i.set("appConfig", configData);
+   * ```
    */
   set(t, e, a = 0) {
     const r = Date.now() + a;
     this.cache.set(t, { data: e, expiry: r });
   }
   /**
-   * Checks if the cache has a valid entry for the given key.
+   * Checks if the cache contains a valid (non-expired) entry for the given key.
+   * Automatically removes expired entries when encountered.
    *
-   * @param key The key to check in the cache.
-   * @returns True if a valid cache entry exists, otherwise false.
+   * @param key - The key to check in the cache
+   * @returns true if a valid cache entry exists, false otherwise
+   * @example
+   * ```typescript
+   * if (Cache.i.has("userProfile")) {
+   *   // Handle cached data exists
+   * }
+   * ```
    */
   has(t) {
     const e = this.cache.get(t);
     return e ? Date.now() > e.expiry ? (this.cache.delete(t), !1) : !0 : !1;
   }
   /**
-   * Gets the cached value for the given key.
+   * Retrieves a value from the cache if it exists and hasn't expired.
+   * Returns null for non-existent or expired entries.
    *
-   * @param key The key to retrieve from the cache.
-   * @returns The cached value or null if not found or expired.
+   * @param key - The key of the cached item to retrieve
+   * @returns The cached value if valid, null otherwise
+   * @example
+   * ```typescript
+   * const userData = Cache.i.get("userProfile");
+   * if (userData) {
+   *   // Use cached data
+   * } else {
+   *   // Handle cache miss
+   * }
+   * ```
    */
   get(t) {
     return this.has(t) ? this.cache.get(t).data : null;
   }
 };
+/**
+ * The singleton instance of the Cache class.
+ *
+ * @private
+ */
 o(f, "_instance");
 let g = f;
 function T(s) {
@@ -109,24 +202,46 @@ async function K(s, t, e) {
 }
 class C {
   /**
-   * Subscribes to the hook
+   * Registers a callback function for a specific route.
+   * If a callback already exists for the route, it will be replaced.
    *
-   * @param routeName - The name of the route to subscribe to
-   * @param callback - The callback to subscribe
+   * @param routeName - The fully qualified name of the route (e.g., "api.users.list")
+   * @param callback - The function to execute when the hook is triggered
+   * @example
+   * ```typescript
+   * Hook.subscribe("api.users.create", () => {
+   *   analytics.trackEvent("User Created");
+   * });
+   * ```
    */
   static subscribe(t, e) {
     this._callbacks.set(t, e);
   }
   /**
-   * Runs the hook
+   * Triggers the callback function associated with a route.
+   * If no callback is registered for the route, the call is silently ignored.
    *
-   * @param routeName - The name of the route to run
+   * @param routeName - The fully qualified name of the route (e.g., "api.users.list")
+   * @example
+   * ```typescript
+   * // This will trigger the callback if one is registered
+   * Hook.run("api.users.create");
+   *
+   * // This will do nothing if no callback is registered
+   * Hook.run("nonexistent.route");
+   * ```
    */
   static run(t) {
     const e = this._callbacks.get(t);
     e && e();
   }
 }
+/**
+ * Internal storage for hook callbacks.
+ * Maps route names to their corresponding callback functions.
+ *
+ * @private
+ */
 o(C, "_callbacks", /* @__PURE__ */ new Map());
 const m = {};
 async function N(s, t, e = {}, a = {}) {
@@ -200,13 +315,37 @@ function U({ route: s, api: t, response: e, data: a }) {
   };
 }
 const l = class l {
+  /** @private */
   constructor() {
+    /**
+     * Map storing all registered elements keyed by their full path.
+     *
+     * @private
+     */
     o(this, "_elements", /* @__PURE__ */ new Map());
+    /**
+     * Reference to the currently active parent element during registration.
+     *
+     * @private
+     */
     o(this, "_currentParent", null);
   }
+  /**
+   * Gets the singleton instance of the Registry.
+   * Creates the instance if it doesn't exist.
+   *
+   * @returns The singleton Registry instance
+   */
   static get i() {
     return l._instance || (l._instance = new l()), l._instance;
   }
+  /**
+   * Registers an element (API, Group, or Route) in the registry.
+   * Sets up parent-child relationships and updates the Klaim object structure.
+   *
+   * @param element - The element to register
+   * @throws Error if registration fails
+   */
   registerElement(t) {
     const e = this._currentParent;
     e && (t.parent = this.getFullPath(e));
@@ -216,18 +355,42 @@ const l = class l {
       e && (r = this.getOrCreateKlaimBranch(e)), r[t.name] = {};
     }
   }
+  /**
+   * Gets the currently active parent element.
+   * Used during element registration to establish hierarchy.
+   *
+   * @returns The current parent element or null if none is set
+   */
   getCurrentParent() {
     return this._currentParent;
   }
+  /**
+   * Sets the current parent element by its full path.
+   * Used to establish context for registering child elements.
+   *
+   * @param fullPath - Full path to the parent element
+   * @throws Error if the specified element doesn't exist or isn't a valid parent type
+   */
   setCurrentParent(t) {
     const e = this._elements.get(t);
     if (!e || e.type !== "api" && e.type !== "group")
       throw new Error(`Element ${t} not found or not a valid parent type`);
     this._currentParent = e;
   }
+  /**
+   * Clears the current parent reference.
+   * Called after finishing registration of child elements.
+   */
   clearCurrentParent() {
     this._currentParent = null;
   }
+  /**
+   * Registers a route element under the current parent.
+   * Sets up the route in the Klaim object hierarchy.
+   *
+   * @param element - The route element to register
+   * @throws Error if no current parent is set or if registration fails
+   */
   registerRoute(t) {
     if (!this._currentParent)
       throw new Error("No current parent set, use Route only inside Api or Group create callback");
@@ -238,6 +401,13 @@ const l = class l {
     const a = this.getElementKey(t);
     this._elements.set(a, t), this.addToKlaimRoute(t);
   }
+  /**
+   * Gets or creates a branch in the Klaim object hierarchy.
+   *
+   * @param parent - The parent element whose branch to get/create
+   * @returns The branch object in the Klaim hierarchy
+   * @private
+   */
   getOrCreateKlaimBranch(t) {
     let e = m;
     const r = this.getFullPath(t).split(".");
@@ -245,6 +415,13 @@ const l = class l {
       e[n] || (e[n] = {}), e = e[n];
     return e;
   }
+  /**
+   * Adds a route to the Klaim object hierarchy.
+   * Creates the necessary function wrapper for API calls.
+   *
+   * @param route - The route element to add
+   * @private
+   */
   addToKlaimRoute(t) {
     if (!t.parent) return;
     const e = t.parent.split(".");
@@ -255,9 +432,23 @@ const l = class l {
       return N(t.parent, t, n, c);
     };
   }
+  /**
+   * Gets the registry key for an element.
+   * The key is the full path of the element in dot notation.
+   *
+   * @param element - The element to get the key for
+   * @returns The element's registry key
+   */
   getElementKey(t) {
     return t ? t.parent ? `${t.parent}.${t.name}` : t.name : "";
   }
+  /**
+   * Gets the full path for an element.
+   * Builds the path by traversing the parent hierarchy.
+   *
+   * @param element - The element to get the path for
+   * @returns The full path in dot notation
+   */
   getFullPath(t) {
     if (!t) return "";
     if (!t.parent) return t.name;
@@ -270,23 +461,56 @@ const l = class l {
     }
     return e.join(".");
   }
+  /**
+   * Gets a route element by API and route names.
+   *
+   * @param apiName - Name of the API containing the route
+   * @param routeName - Name of the route to retrieve
+   * @returns The route element or undefined if not found
+   */
   getRoute(t, e) {
     return this._elements.get(`${t}.${e}`);
   }
+  /**
+   * Gets all child elements for a given parent path.
+   *
+   * @param elementPath - Full path of the parent element
+   * @returns Array of child elements
+   */
   getChildren(t) {
     const e = [];
     return this._elements.forEach((a) => {
       a.parent === t && e.push(a);
     }), e;
   }
+  /**
+   * Updates an element in the registry.
+   *
+   * @param element - The element to update
+   * @returns The updated element or the original if not found
+   */
   static updateElement(t) {
     return l.i._elements.get(l.i.getElementKey(t)) || t;
   }
+  /**
+   * Gets an API element by name.
+   *
+   * @param name - Name of the API to retrieve
+   * @returns The API element or undefined if not found
+   */
   getApi(t) {
     const e = this._elements.get(t);
     if (e)
       return e.type === "api" ? e : this.findApi(e);
   }
+  /**
+   * Finds the parent API element for a given element.
+   * Traverses up the parent hierarchy until an API element is found.
+   *
+   * @param element - The element to find the API for
+   * @returns The parent API element or undefined if not found
+   * @private
+   */
   findApi(t) {
     if (!t || !t.parent) return;
     const e = t.parent.split(".");
@@ -296,50 +520,171 @@ const l = class l {
     }
   }
 };
+/** Singleton instance of the Registry */
 o(l, "_instance");
 let i = l;
 class b extends y {
+  /**
+   * Creates a new API instance and registers it in the global Registry.
+   *
+   * @param name - The name of the API. Will be converted to camelCase if necessary
+   * @param url - The base URL for the API
+   * @param callback - Configuration callback where routes and other settings are defined
+   * @param headers - Optional headers to be included with all requests to this API
+   * @returns The created API instance
+   * @throws Error if the API registration fails
+   * @example
+   * ```typescript
+   * Api.create("userApi", "https://api.users.com", () => {
+   *   Route.get("getUser", "/users/[id]");
+   * }, { "API-Key": "secret" });
+   * ```
+   */
   static create(t, e, a, r = {}) {
     const n = P(t);
     n !== t && console.warn(`API name "${t}" has been camelCased to "${n}"`);
     const c = new b(n, e, r);
     return i.i.registerElement(c), i.i.setCurrentParent(n), a(), i.i.clearCurrentParent(), c;
   }
+  /**
+   * Creates a new Api instance.
+   * Private constructor to ensure APIs are only created through the static create method.
+   *
+   * @param name - The camelCased name of the API
+   * @param url - The base URL for the API
+   * @param headers - Optional headers to be included with all requests to this API
+   */
   constructor(t, e, a = {}) {
     super("api", t, e, a);
   }
 }
 class E extends y {
+  /**
+   * Creates a new group and registers it in the Registry.
+   * Supports nested groups and inheritable configurations.
+   *
+   * @param name - Name of the group (will be converted to camelCase)
+   * @param callback - Configuration callback for defining routes and nested groups
+   * @returns The created group instance
+   * @throws Error if group creation fails or parent context is invalid
+   * @example
+   * ```typescript
+   * Group.create("admin", () => {
+   *   Group.create("users", () => {
+   *     Route.get("list", "/admin/users");
+   *   });
+   * }).before(authMiddleware);
+   * ```
+   */
   static create(t, e) {
     const a = P(t), r = i.i.getCurrentParent(), n = r ? i.i.getFullPath(r) : "", c = n ? `${n}.${a}` : a, u = new E(a, "");
     a !== t && console.warn(`Group name "${t}" has been camelCased to "${a}"`), i.i.registerElement(u);
     const h = i.i.getCurrentParent();
     return i.i.setCurrentParent(c), e(), h ? i.i.setCurrentParent(i.i.getFullPath(h)) : i.i.clearCurrentParent(), u;
   }
+  /**
+   * Creates a new Group instance.
+   * Private constructor to ensure groups are only created through the static create method.
+   *
+   * @param name - The camelCased name of the group
+   * @param url - Base URL for the group (usually empty)
+   * @param headers - Optional headers shared by all routes in the group
+   * @private
+   */
   constructor(t, e, a = {}) {
     super("group", t, e, a);
   }
-  // Overriding parent methods to ensure group-specific behavior
+  /**
+   * Enables caching for the group and all its child routes.
+   * Child routes can override the cache duration with their own settings.
+   *
+   * @param duration - Cache duration in seconds (default: 20)
+   * @returns this group instance for chaining
+   * @example
+   * ```typescript
+   * Group.create("users", () => {
+   *   Route.get("list", "/users");
+   * }).withCache(300); // Cache all routes for 5 minutes
+   * ```
+   */
   withCache(t = 20) {
     return super.withCache(t), i.i.getChildren(i.i.getFullPath(this)).forEach((e) => {
       e.cache || (e.cache = t);
     }), this;
   }
+  /**
+   * Enables retry mechanism for the group and all its child routes.
+   * Child routes can override the retry count with their own settings.
+   *
+   * @param maxRetries - Maximum number of retry attempts (default: 2)
+   * @returns this group instance for chaining
+   * @example
+   * ```typescript
+   * Group.create("users", () => {
+   *   Route.get("list", "/users");
+   * }).withRetry(3); // Retry failed requests up to 3 times
+   * ```
+   */
   withRetry(t = 2) {
     return super.withRetry(t), i.i.getChildren(i.i.getFullPath(this)).forEach((e) => {
       e.retry || (e.retry = t);
     }), this;
   }
+  /**
+   * Adds a before-request middleware to the group and all its child routes.
+   * Child routes can override this middleware with their own.
+   *
+   * @param callback - Middleware function to execute before requests
+   * @returns this group instance for chaining
+   * @example
+   * ```typescript
+   * Group.create("admin", () => {
+   *   Route.get("stats", "/admin/stats");
+   * }).before(({ config }) => {
+   *   config.headers.Authorization = getAdminToken();
+   * });
+   * ```
+   */
   before(t) {
     return super.before(t), i.i.getChildren(i.i.getFullPath(this)).forEach((e) => {
       e.callbacks.before || (e.callbacks.before = t);
     }), this;
   }
+  /**
+   * Adds an after-request middleware to the group and all its child routes.
+   * Child routes can override this middleware with their own.
+   *
+   * @param callback - Middleware function to execute after requests
+   * @returns this group instance for chaining
+   * @example
+   * ```typescript
+   * Group.create("users", () => {
+   *   Route.get("list", "/users");
+   * }).after(({ data }) => {
+   *   console.log(`Fetched ${data.length} users`);
+   * });
+   * ```
+   */
   after(t) {
     return super.after(t), i.i.getChildren(i.i.getFullPath(this)).forEach((e) => {
       e.callbacks.after || (e.callbacks.after = t);
     }), this;
   }
+  /**
+   * Adds a request lifecycle middleware to the group and all its child routes.
+   * Child routes can override this middleware with their own.
+   *
+   * @param callback - Middleware function to execute during requests
+   * @returns this group instance for chaining
+   * @example
+   * ```typescript
+   * Group.create("api", () => {
+   *   Route.get("status", "/status");
+   * }).onCall(() => {
+   *   metrics.incrementApiCalls();
+   * });
+   * ```
+   */
   onCall(t) {
     return super.onCall(t), i.i.getChildren(i.i.getFullPath(this)).forEach((e) => {
       e.callbacks.call || (e.callbacks.call = t);
@@ -347,13 +692,44 @@ class E extends y {
   }
 }
 class $ extends y {
+  /**
+   * Creates a new Route instance.
+   *
+   * @param name - Unique name for the route
+   * @param url - URL path for the route, can include parameters in [param] format
+   * @param headers - Optional HTTP headers specific to this route
+   * @param method - HTTP method for this route
+   */
   constructor(t, e, a = {}, r = "GET") {
     super("route", t, e, a), this.method = r, this.detectArguments();
   }
+  /**
+   * Internal helper to create and register a new route.
+   *
+   * @param name - Route name
+   * @param url - Route URL path
+   * @param headers - Route-specific headers
+   * @param method - HTTP method
+   * @returns The created route element
+   * @private
+   */
   static createRoute(t, e, a = {}, r) {
     const n = new $(t, e, a, r);
     return i.i.registerRoute(n), n;
   }
+  /**
+   * Creates a GET route.
+   *
+   * @param name - Route name
+   * @param url - Route URL path
+   * @param headers - Route-specific headers
+   * @returns The created GET route
+   * @example
+   * ```typescript
+   * Route.get("listUsers", "/users");
+   * Route.get("getUser", "/users/[id]");
+   * ```
+   */
   static get(t, e, a = {}) {
     return this.createRoute(
       t,
@@ -363,6 +739,18 @@ class $ extends y {
       /* GET */
     );
   }
+  /**
+   * Creates a POST route.
+   *
+   * @param name - Route name
+   * @param url - Route URL path
+   * @param headers - Route-specific headers
+   * @returns The created POST route
+   * @example
+   * ```typescript
+   * Route.post("createUser", "/users");
+   * ```
+   */
   static post(t, e, a = {}) {
     return this.createRoute(
       t,
@@ -372,6 +760,18 @@ class $ extends y {
       /* POST */
     );
   }
+  /**
+   * Creates a PUT route.
+   *
+   * @param name - Route name
+   * @param url - Route URL path
+   * @param headers - Route-specific headers
+   * @returns The created PUT route
+   * @example
+   * ```typescript
+   * Route.put("updateUser", "/users/[id]");
+   * ```
+   */
   static put(t, e, a = {}) {
     return this.createRoute(
       t,
@@ -381,6 +781,18 @@ class $ extends y {
       /* PUT */
     );
   }
+  /**
+   * Creates a DELETE route.
+   *
+   * @param name - Route name
+   * @param url - Route URL path
+   * @param headers - Route-specific headers
+   * @returns The created DELETE route
+   * @example
+   * ```typescript
+   * Route.delete("deleteUser", "/users/[id]");
+   * ```
+   */
   static delete(t, e, a = {}) {
     return this.createRoute(
       t,
@@ -390,6 +802,18 @@ class $ extends y {
       /* DELETE */
     );
   }
+  /**
+   * Creates a PATCH route.
+   *
+   * @param name - Route name
+   * @param url - Route URL path
+   * @param headers - Route-specific headers
+   * @returns The created PATCH route
+   * @example
+   * ```typescript
+   * Route.patch("updateUserStatus", "/users/[id]/status");
+   * ```
+   */
   static patch(t, e, a = {}) {
     return this.createRoute(
       t,
@@ -399,6 +823,18 @@ class $ extends y {
       /* PATCH */
     );
   }
+  /**
+   * Creates an OPTIONS route.
+   *
+   * @param name - Route name
+   * @param url - Route URL path
+   * @param headers - Route-specific headers
+   * @returns The created OPTIONS route
+   * @example
+   * ```typescript
+   * Route.options("userOptions", "/users");
+   * ```
+   */
   static options(t, e, a = {}) {
     return this.createRoute(
       t,
@@ -408,6 +844,13 @@ class $ extends y {
       /* OPTIONS */
     );
   }
+  /**
+   * Detects URL parameters in the route path.
+   * Parameters are defined using square brackets, e.g., [id] in /users/[id].
+   * Detected parameters are stored in the arguments Set.
+   *
+   * @private
+   */
   detectArguments() {
     const t = this.url.match(/\[([^\]]+)]/g);
     t && t.forEach((e) => {
@@ -415,6 +858,17 @@ class $ extends y {
       this.arguments.add(a);
     });
   }
+  /**
+   * Sets up response validation using a schema.
+   *
+   * @param schema - Validation schema (e.g., Yup schema)
+   * @returns This route instance for chaining
+   * @example
+   * ```typescript
+   * Route.get("getUser", "/users/[id]")
+   *   .validate(userSchema);
+   * ```
+   */
   validate(t) {
     return this.schema = t, this;
   }