@jayethian/axiom 0.1.0 → 0.1.1

package/README.md

@@ -1 +1,150 @@
-# axiom
+<div align="center">
+  <img src="./assets/logo.png" alt="axiom logo" width="400" />
+  <h1>Axiom</h1>
+
+  <h3>Resilient, offline-first networking for modern React apps.</h3>
+  
+  <p>
+    <a href="https://www.npmjs.com/package/@jayethian/axiom">
+      <img src="https://img.shields.io/npm/v/@jayethian/axiom.svg?style=flat-square" alt="npm version" />
+    </a>
+    <a href="https://www.npmjs.com/package/@jayethian/axiom">
+      <img src="https://img.shields.io/npm/dm/@jayethian/axiom.svg?style=flat-square" alt="npm downloads" />
+    </a>
+    <a href="https://opensource.org/licenses/MIT">
+      <img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" alt="License: MIT" />
+    </a>
+    <img src="https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg?style=flat-square" alt="TypeScript" />
+  </p>
+</div>
+
+<br />
+
+## The Problem
+Standard HTTP clients like **Axios** or **Fetch** assume a stable connection. When a user submits data in a dead zone (elevators, basements, rural areas), the request simply fails. Without a complex manual retry system, **that data is gone forever.**
+
+## The Axiom Way
+Axiom intercepts network failures and timeouts. Instead of throwing an error, it serializes the request and moves it to a persistent local queue. When the connection returns, Axiom flushes the queue automatically.
+
+```typescript
+// Standard Fetch: Fails and loses data when offline.
+await fetch('/api/orders', { method: 'POST', body: data }); 
+
+// Axiom: Intercepts drop, queues safely, and syncs when back online.
+await axiom.post('/api/orders', data); 
+
+```
+
+---
+
+## Key Features
+
+* **📱 Mobile-First Resilience:** Specifically tuned for React Native's shaky connectivity.
+* **🔄 Autonomous Background Sync:** Replays the queue the moment a signal is detected.
+* **⚡ Priority Lanes:** Ensure critical data (e.g., payments) jumps to the front of the queue ahead of background tasks (e.g., analytics).
+* **🛡️ Just-In-Time Headers:** Refresh Auth Tokens immediately before syncing to prevent `401 Unauthorized` errors on old requests.
+* **💾 Storage Agnostic:** Use the high-performance storage of your choice (**MMKV**, **SQLite**, **IndexedDB**).
+* **🪦 Dead Letter Queues:** Protects your app from infinite loops by isolating permanently failing requests.
+
+---
+
+## Installation
+
+```bash
+yarn add @jayethian/axiom
+# or
+npm install @jayethian/axiom
+
+```
+
+---
+
+## Setup & Usage
+
+### 1. Initialize the Provider
+
+Wrap your app root. Axiom doesn't force a specific network library on you—just pass in your preferred listener (like NetInfo).
+
+```tsx
+import { AxiomProvider } from '@jayethian/axiom';
+import NetInfo from '@react-native-community/netinfo';
+
+export default function App() {
+  return (
+    <AxiomProvider
+      config={{ baseURL: '[https://api.myapp.com](https://api.myapp.com)', timeout: 10000 }}
+      networkListener={(callback) => {
+        return NetInfo.addEventListener(state => callback(!!state.isConnected));
+      }}
+    >
+      <Main />
+    </AxiomProvider>
+  );
+}
+
+```
+
+### 2. Use Hooks for Better UX
+
+Keep your users informed when they are working offline.
+
+```tsx
+import { axiom, useAxiomQueue } from '@jayethian/axiom';
+
+const { isOnline } = useAxiomQueue();
+
+const onSave = async (data) => {
+  const res = await axiom.post('/profile', data, { priority: 'urgent' });
+  
+  if (res.isQueued) {
+    showToast("Working offline. Your changes will sync automatically!");
+  }
+};
+
+```
+
+---
+
+## Advanced Configuration
+
+### Priority Lanes
+
+Prevent large background uploads from blocking small, critical API calls.
+
+```typescript
+// This stays at the back of the line
+axiom.post('/analytics', logData, { priority: 'background' });
+
+// This jumps to the front
+axiom.post('/chat/send', message, { priority: 'urgent' });
+
+```
+
+### Just-In-Time Headers
+
+Refresh your JWT right before the queue fires to ensure every request is authorized.
+
+```tsx
+<AxiomProvider
+  config={{
+    onBeforeSync: async (request) => {
+      const token = await getFreshToken();
+      return {
+        ...request,
+        headers: { ...request.headers, Authorization: `Bearer ${token}` }
+      };
+    }
+  }}
+>
+
+```
+
+---
+
+## Contributing
+
+We welcome contributions! Please feel free to submit a [Pull Request](https://www.google.com/search?q=https://github.com/jayethian/axiom/pulls) or report a [Bug](https://www.google.com/search?q=https://github.com/jayethian/axiom/issues).
+
+## License
+
+Distributed under the MIT License. See `LICENSE` for more information. Built with ⚡ by [Jayetheus](https://www.google.com/search?q=https://github.com/jayethian).

package/dist/index.d.mts

@@ -1,6 +1,11 @@
 import React from 'react';
 
+/** * Defines how the request should be treated when the queue flushes.
+ * Urgent requests bypass the background queue entirely if the network is active.
+ */
 type RequestPriority = 'urgent' | 'background';
+/** * Represents a serialized HTTP request frozen in offline storage.
+ */
 interface QueuedRequest {
     id: string;
     timestamp: number;
@@ -11,13 +16,32 @@ interface QueuedRequest {
     priority: RequestPriority;
     retryCount: number;
 }
+/** * Global configuration for the Axiom engine initialized on startup.
+ */
 interface AxiomConfig {
+    /** The base URL prepended to all request paths. */
     baseURL?: string;
+    /** Global headers applied to every request (e.g., Auth tokens). */
     defaultHeaders?: Record<string, string>;
+    /** The maximum number of times a queued request will attempt to sync before failing permanently. */
     maxRetries?: number;
+    /** Global timeout in milliseconds before a request is aborted and queued. */
+    timeout?: number;
+    /** Middleware hook triggered immediately before a queued request is synced. Ideal for refreshing Auth tokens. */
     onBeforeSync?: (request: QueuedRequest) => Promise<QueuedRequest>;
+    /** Callback triggered when a request exceeds maxRetries and is permanently removed from the queue. */
     onDeadLetter?: (request: QueuedRequest, error: Error) => void;
 }
+/** * Per-request configuration options that override the global configuration.
+ */
+interface AxiomRequestOptions {
+    /** Overrides the queue sorting behavior for this specific request. */
+    priority?: RequestPriority;
+    /** Overrides the global timeout limit for this specific request. */
+    timeout?: number;
+    /** Specific headers to append to this single request (e.g., custom Content-Type). */
+    headers?: Record<string, string>;
+}
 
 interface AxiomStorageAdapter {
     /** Saves a request to the persistent queue */
@@ -43,40 +67,88 @@ declare class AxiomEngine {
     private storage;
     private syncManager;
     /**
-     * Initializes the Axiom engine with your specific rules and storage.
+     * Initializes the Axiom engine with global configuration and a storage adapter.
+     * This must be called before making any requests to enable persistence.
+     * * @param config - Global configuration (baseURL, timeouts, custom headers, etc.)
+     * @param storageAdapter - Optional custom adapter (e.g., MMKV). Defaults to in-memory storage.
      */
     create(config: AxiomConfig, storageAdapter?: AxiomStorageAdapter): void;
+    /**
+     * Manually triggers the background sync manager to flush all pending queued requests.
+     * Note: This is automatically handled by `AxiomProvider` when the network reconnects.
+     */
     forceSync(): Promise<void>;
     /**
-     * Generates a unique ID for queued requests.
+     * Generates a unique collision-resistant ID for queued requests.
      */
     private generateId;
     /**
-     * The core POST method.
+     * Executes an HTTP GET request.
+     * If the network is unavailable or times out, the request is safely queued.
+     * * @param url - The endpoint URL (appended to baseURL if configured).
+     * @param options - Request-specific options (priority lanes, timeout overrides).
+     * @returns A promise resolving to the response data, status code, and queue state.
+     */
+    get<T>(url: string, options?: AxiomRequestOptions): Promise<{
+        data?: T;
+        status: number;
+        isQueued: boolean;
+    }>;
+    /**
+     * Executes an HTTP POST request.
+     * If the network is unavailable or times out, the payload is safely queued.
+     * * @param url - The endpoint URL.
+     * @param data - The payload object to be serialized and sent.
+     * @param options - Request-specific options.
+     */
+    post<T>(url: string, data?: any, options?: AxiomRequestOptions): Promise<{
+        data?: T;
+        status: number;
+        isQueued: boolean;
+    }>;
+    /**
+     * Executes an HTTP PUT request to entirely replace a resource.
+     * * @param url - The endpoint URL.
+     * @param data - The payload object to be serialized and sent.
+     * @param options - Request-specific options.
+     */
+    put<T>(url: string, data?: any, options?: AxiomRequestOptions): Promise<{
+        data?: T;
+        status: number;
+        isQueued: boolean;
+    }>;
+    /**
+     * Executes an HTTP PATCH request to partially update a resource.
+     * * @param url - The endpoint URL.
+     * @param data - The partial payload object to be serialized and sent.
+     * @param options - Request-specific options.
      */
-    post<T>(url: string, data?: any, options?: {
-        priority?: RequestPriority;
-    }): Promise<{
+    patch<T>(url: string, data?: any, options?: AxiomRequestOptions): Promise<{
         data?: T;
         status: number;
         isQueued: boolean;
     }>;
-    /** The core GET method.
-     * Note: GET requests typically don't have a body, but we still want to queue them if offline.
+    /**
+     * Executes an HTTP DELETE request.
+     * * @param url - The endpoint URL.
+     * @param options - Request-specific options.
      */
-    get<T>(url: string, options?: {
-        priority?: RequestPriority;
-    }): Promise<{
+    delete<T>(url: string, options?: AxiomRequestOptions): Promise<{
         data?: T;
         status: number;
         isQueued: boolean;
     }>;
+    /**
+     * Internal helper to consolidate request preparation and keep the engine DRY.
+     */
+    private prepareRequest;
     /**
      * Internal logic to fire the request or catch the network drop.
+     * Handles timeout cancellations via AbortController.
      */
     private attemptFetch;
     /**
-     * Saves the request to whatever storage adapter was provided on startup.
+     * Saves the request to the configured storage adapter.
      */
     private enqueueRequest;
 }
@@ -99,4 +171,4 @@ declare function useAxiomQueue(): {
     forceSync: () => Promise<void>;
 };
 
-export { type AxiomConfig, AxiomEngine, AxiomProvider, type AxiomStorageAdapter, MemoryStorageAdapter, type QueuedRequest, type RequestPriority, axiom, useAxiomQueue };
+export { type AxiomConfig, AxiomEngine, AxiomProvider, type AxiomRequestOptions, type AxiomStorageAdapter, MemoryStorageAdapter, type QueuedRequest, type RequestPriority, axiom, useAxiomQueue };

package/dist/index.d.ts

@@ -1,6 +1,11 @@
 import React from 'react';
 
+/** * Defines how the request should be treated when the queue flushes.
+ * Urgent requests bypass the background queue entirely if the network is active.
+ */
 type RequestPriority = 'urgent' | 'background';
+/** * Represents a serialized HTTP request frozen in offline storage.
+ */
 interface QueuedRequest {
     id: string;
     timestamp: number;
@@ -11,13 +16,32 @@ interface QueuedRequest {
     priority: RequestPriority;
     retryCount: number;
 }
+/** * Global configuration for the Axiom engine initialized on startup.
+ */
 interface AxiomConfig {
+    /** The base URL prepended to all request paths. */
     baseURL?: string;
+    /** Global headers applied to every request (e.g., Auth tokens). */
     defaultHeaders?: Record<string, string>;
+    /** The maximum number of times a queued request will attempt to sync before failing permanently. */
     maxRetries?: number;
+    /** Global timeout in milliseconds before a request is aborted and queued. */
+    timeout?: number;
+    /** Middleware hook triggered immediately before a queued request is synced. Ideal for refreshing Auth tokens. */
     onBeforeSync?: (request: QueuedRequest) => Promise<QueuedRequest>;
+    /** Callback triggered when a request exceeds maxRetries and is permanently removed from the queue. */
     onDeadLetter?: (request: QueuedRequest, error: Error) => void;
 }
+/** * Per-request configuration options that override the global configuration.
+ */
+interface AxiomRequestOptions {
+    /** Overrides the queue sorting behavior for this specific request. */
+    priority?: RequestPriority;
+    /** Overrides the global timeout limit for this specific request. */
+    timeout?: number;
+    /** Specific headers to append to this single request (e.g., custom Content-Type). */
+    headers?: Record<string, string>;
+}
 
 interface AxiomStorageAdapter {
     /** Saves a request to the persistent queue */
@@ -43,40 +67,88 @@ declare class AxiomEngine {
     private storage;
     private syncManager;
     /**
-     * Initializes the Axiom engine with your specific rules and storage.
+     * Initializes the Axiom engine with global configuration and a storage adapter.
+     * This must be called before making any requests to enable persistence.
+     * * @param config - Global configuration (baseURL, timeouts, custom headers, etc.)
+     * @param storageAdapter - Optional custom adapter (e.g., MMKV). Defaults to in-memory storage.
      */
     create(config: AxiomConfig, storageAdapter?: AxiomStorageAdapter): void;
+    /**
+     * Manually triggers the background sync manager to flush all pending queued requests.
+     * Note: This is automatically handled by `AxiomProvider` when the network reconnects.
+     */
     forceSync(): Promise<void>;
     /**
-     * Generates a unique ID for queued requests.
+     * Generates a unique collision-resistant ID for queued requests.
      */
     private generateId;
     /**
-     * The core POST method.
+     * Executes an HTTP GET request.
+     * If the network is unavailable or times out, the request is safely queued.
+     * * @param url - The endpoint URL (appended to baseURL if configured).
+     * @param options - Request-specific options (priority lanes, timeout overrides).
+     * @returns A promise resolving to the response data, status code, and queue state.
+     */
+    get<T>(url: string, options?: AxiomRequestOptions): Promise<{
+        data?: T;
+        status: number;
+        isQueued: boolean;
+    }>;
+    /**
+     * Executes an HTTP POST request.
+     * If the network is unavailable or times out, the payload is safely queued.
+     * * @param url - The endpoint URL.
+     * @param data - The payload object to be serialized and sent.
+     * @param options - Request-specific options.
+     */
+    post<T>(url: string, data?: any, options?: AxiomRequestOptions): Promise<{
+        data?: T;
+        status: number;
+        isQueued: boolean;
+    }>;
+    /**
+     * Executes an HTTP PUT request to entirely replace a resource.
+     * * @param url - The endpoint URL.
+     * @param data - The payload object to be serialized and sent.
+     * @param options - Request-specific options.
+     */
+    put<T>(url: string, data?: any, options?: AxiomRequestOptions): Promise<{
+        data?: T;
+        status: number;
+        isQueued: boolean;
+    }>;
+    /**
+     * Executes an HTTP PATCH request to partially update a resource.
+     * * @param url - The endpoint URL.
+     * @param data - The partial payload object to be serialized and sent.
+     * @param options - Request-specific options.
      */
-    post<T>(url: string, data?: any, options?: {
-        priority?: RequestPriority;
-    }): Promise<{
+    patch<T>(url: string, data?: any, options?: AxiomRequestOptions): Promise<{
         data?: T;
         status: number;
         isQueued: boolean;
     }>;
-    /** The core GET method.
-     * Note: GET requests typically don't have a body, but we still want to queue them if offline.
+    /**
+     * Executes an HTTP DELETE request.
+     * * @param url - The endpoint URL.
+     * @param options - Request-specific options.
      */
-    get<T>(url: string, options?: {
-        priority?: RequestPriority;
-    }): Promise<{
+    delete<T>(url: string, options?: AxiomRequestOptions): Promise<{
         data?: T;
         status: number;
         isQueued: boolean;
     }>;
+    /**
+     * Internal helper to consolidate request preparation and keep the engine DRY.
+     */
+    private prepareRequest;
     /**
      * Internal logic to fire the request or catch the network drop.
+     * Handles timeout cancellations via AbortController.
      */
     private attemptFetch;
     /**
-     * Saves the request to whatever storage adapter was provided on startup.
+     * Saves the request to the configured storage adapter.
      */
     private enqueueRequest;
 }
@@ -99,4 +171,4 @@ declare function useAxiomQueue(): {
     forceSync: () => Promise<void>;
 };
 
-export { type AxiomConfig, AxiomEngine, AxiomProvider, type AxiomStorageAdapter, MemoryStorageAdapter, type QueuedRequest, type RequestPriority, axiom, useAxiomQueue };
+export { type AxiomConfig, AxiomEngine, AxiomProvider, type AxiomRequestOptions, type AxiomStorageAdapter, MemoryStorageAdapter, type QueuedRequest, type RequestPriority, axiom, useAxiomQueue };

package/dist/index.js

@@ -56,6 +56,7 @@ var SyncManager = class {
   }
   /**
    * The master trigger. Call this when the OS reports network is back online.
+   * Automatically sorts requests so 'urgent' items bypass 'background' items.
    */
   async flushQueue() {
     if (this.isSyncing) return;
@@ -63,11 +64,15 @@ var SyncManager = class {
     try {
       const pending = await this.storage.getAll();
       if (pending.length === 0) {
-        this.isSyncing = false;
         return;
       }
       console.log(`[Axiom] Network restored. Syncing ${pending.length} queued requests...`);
-      for (const request of pending) {
+      const sortedQueue = pending.sort((a, b) => {
+        if (a.priority === "urgent" && b.priority !== "urgent") return -1;
+        if (a.priority !== "urgent" && b.priority === "urgent") return 1;
+        return a.timestamp - b.timestamp;
+      });
+      for (const request of sortedQueue) {
         await this.processRequest(request);
       }
     } finally {
@@ -83,16 +88,22 @@ var SyncManager = class {
       try {
         reqToSync = await this.config.onBeforeSync(request);
       } catch (error) {
-        console.error(`[Axiom] onBeforeSync failed for ${request.id}. Skipping.`);
+        console.error(`[Axiom] onBeforeSync failed for ${request.id}. Marking as failure.`);
+        await this.handleFailure(request);
         return;
       }
     }
+    const controller = new AbortController();
+    const timeoutMs = this.config.timeout || 1e4;
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
     try {
       const response = await fetch(reqToSync.url, {
         method: reqToSync.method,
         headers: reqToSync.headers,
-        body: reqToSync.body
+        body: reqToSync.body,
+        signal: controller.signal
       });
+      clearTimeout(timeoutId);
       if (response.ok || response.status >= 400 && response.status < 500) {
         await this.storage.remove(reqToSync.id);
         console.log(`[Axiom] Request ${reqToSync.id} synced successfully.`);
@@ -100,6 +111,7 @@ var SyncManager = class {
         await this.handleFailure(reqToSync);
       }
     } catch (error) {
+      clearTimeout(timeoutId);
       await this.handleFailure(reqToSync);
     }
   }
@@ -108,7 +120,7 @@ var SyncManager = class {
    */
   async handleFailure(request) {
     request.retryCount += 1;
-    const maxRetries = this.config.maxRetries || 3;
+    const maxRetries = this.config.maxRetries ?? 3;
     if (request.retryCount >= maxRetries) {
       console.warn(`[Axiom] Request ${request.id} failed ${maxRetries} times. Moving to Dead Letter.`);
       await this.storage.remove(request.id);
@@ -128,7 +140,10 @@ var AxiomEngine = class {
     this.storage = new MemoryStorageAdapter();
   }
   /**
-   * Initializes the Axiom engine with your specific rules and storage.
+   * Initializes the Axiom engine with global configuration and a storage adapter.
+   * This must be called before making any requests to enable persistence.
+   * * @param config - Global configuration (baseURL, timeouts, custom headers, etc.)
+   * @param storageAdapter - Optional custom adapter (e.g., MMKV). Defaults to in-memory storage.
    */
   create(config, storageAdapter) {
     this.config = config;
@@ -137,6 +152,10 @@ var AxiomEngine = class {
     }
     this.syncManager = new SyncManager(this.storage, this.config);
   }
+  /**
+   * Manually triggers the background sync manager to flush all pending queued requests.
+   * Note: This is automatically handled by `AxiomProvider` when the network reconnects.
+   */
   async forceSync() {
     if (!this.syncManager) {
       console.error("[Axiom] Engine not initialized. Call axiom.create() first.");
@@ -145,59 +164,94 @@ var AxiomEngine = class {
     await this.syncManager.flushQueue();
   }
   /**
-   * Generates a unique ID for queued requests.
+   * Generates a unique collision-resistant ID for queued requests.
    */
   generateId() {
     return Math.random().toString(36).substring(2, 15) + Date.now().toString(36);
   }
   /**
-   * The core POST method. 
+   * Executes an HTTP GET request. 
+   * If the network is unavailable or times out, the request is safely queued.
+   * * @param url - The endpoint URL (appended to baseURL if configured).
+   * @param options - Request-specific options (priority lanes, timeout overrides).
+   * @returns A promise resolving to the response data, status code, and queue state.
+   */
+  async get(url, options) {
+    return this.prepareRequest("GET", url, void 0, options);
+  }
+  /**
+   * Executes an HTTP POST request.
+   * If the network is unavailable or times out, the payload is safely queued.
+   * * @param url - The endpoint URL.
+   * @param data - The payload object to be serialized and sent.
+   * @param options - Request-specific options.
    */
   async post(url, data, options) {
-    const fullUrl = this.config.baseURL ? `${this.config.baseURL}${url}` : url;
-    const request = {
-      id: this.generateId(),
-      timestamp: Date.now(),
-      url: fullUrl,
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        ...this.config.defaultHeaders || {}
-      },
-      body: data ? JSON.stringify(data) : void 0,
-      priority: options?.priority || "urgent",
-      retryCount: 0
-    };
-    return this.attemptFetch(request);
+    return this.prepareRequest("POST", url, data, options);
   }
-  /** The core GET method.
-   * Note: GET requests typically don't have a body, but we still want to queue them if offline.
+  /**
+   * Executes an HTTP PUT request to entirely replace a resource.
+   * * @param url - The endpoint URL.
+   * @param data - The payload object to be serialized and sent.
+   * @param options - Request-specific options.
    */
-  async get(url, options) {
+  async put(url, data, options) {
+    return this.prepareRequest("PUT", url, data, options);
+  }
+  /**
+   * Executes an HTTP PATCH request to partially update a resource.
+   * * @param url - The endpoint URL.
+   * @param data - The partial payload object to be serialized and sent.
+   * @param options - Request-specific options.
+   */
+  async patch(url, data, options) {
+    return this.prepareRequest("PATCH", url, data, options);
+  }
+  /**
+   * Executes an HTTP DELETE request.
+   * * @param url - The endpoint URL.
+   * @param options - Request-specific options.
+   */
+  async delete(url, options) {
+    return this.prepareRequest("DELETE", url, void 0, options);
+  }
+  /**
+   * Internal helper to consolidate request preparation and keep the engine DRY.
+   */
+  async prepareRequest(method, url, data, options) {
     const fullUrl = this.config.baseURL ? `${this.config.baseURL}${url}` : url;
+    const headers = { ...this.config.defaultHeaders || {} };
+    if (options?.headers) {
+      Object.assign(headers, options.headers);
+    }
     const request = {
       id: this.generateId(),
       timestamp: Date.now(),
       url: fullUrl,
-      method: "GET",
-      headers: {
-        ...this.config.defaultHeaders || {}
-      },
+      method,
+      headers,
+      body: data ? JSON.stringify(data) : void 0,
       priority: options?.priority || "urgent",
       retryCount: 0
     };
-    return this.attemptFetch(request);
+    const timeoutMs = options?.timeout || this.config.timeout || 8e3;
+    return this.attemptFetch(request, timeoutMs);
   }
   /**
    * Internal logic to fire the request or catch the network drop.
+   * Handles timeout cancellations via AbortController.
    */
-  async attemptFetch(request) {
+  async attemptFetch(request, timeoutMs) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
     try {
       const response = await fetch(request.url, {
         method: request.method,
         headers: request.headers,
-        body: request.body
+        body: request.body,
+        signal: controller.signal
       });
+      clearTimeout(timeoutId);
       if (response.ok) {
         const responseData = await response.json().catch(() => null);
         return { data: responseData, status: response.status, isQueued: false };
@@ -207,12 +261,16 @@ var AxiomEngine = class {
       }
       return { status: response.status, isQueued: false };
     } catch (error) {
+      clearTimeout(timeoutId);
+      if (error.name === "AbortError") {
+        console.warn(`[Axiom] Request to ${request.url} timed out after ${timeoutMs}ms. Queuing for retry.`);
+      }
       await this.enqueueRequest(request);
       return { status: 202, isQueued: true };
     }
   }
   /**
-   * Saves the request to whatever storage adapter was provided on startup.
+   * Saves the request to the configured storage adapter.
    */
   async enqueueRequest(request) {
     console.warn(`[Axiom] Network unreachable. Queuing request ${request.id}`);

package/dist/index.mjs

@@ -26,6 +26,7 @@ var SyncManager = class {
   }
   /**
    * The master trigger. Call this when the OS reports network is back online.
+   * Automatically sorts requests so 'urgent' items bypass 'background' items.
    */
   async flushQueue() {
     if (this.isSyncing) return;
@@ -33,11 +34,15 @@ var SyncManager = class {
     try {
       const pending = await this.storage.getAll();
       if (pending.length === 0) {
-        this.isSyncing = false;
         return;
       }
       console.log(`[Axiom] Network restored. Syncing ${pending.length} queued requests...`);
-      for (const request of pending) {
+      const sortedQueue = pending.sort((a, b) => {
+        if (a.priority === "urgent" && b.priority !== "urgent") return -1;
+        if (a.priority !== "urgent" && b.priority === "urgent") return 1;
+        return a.timestamp - b.timestamp;
+      });
+      for (const request of sortedQueue) {
         await this.processRequest(request);
       }
     } finally {
@@ -53,16 +58,22 @@ var SyncManager = class {
       try {
         reqToSync = await this.config.onBeforeSync(request);
       } catch (error) {
-        console.error(`[Axiom] onBeforeSync failed for ${request.id}. Skipping.`);
+        console.error(`[Axiom] onBeforeSync failed for ${request.id}. Marking as failure.`);
+        await this.handleFailure(request);
         return;
       }
     }
+    const controller = new AbortController();
+    const timeoutMs = this.config.timeout || 1e4;
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
     try {
       const response = await fetch(reqToSync.url, {
         method: reqToSync.method,
         headers: reqToSync.headers,
-        body: reqToSync.body
+        body: reqToSync.body,
+        signal: controller.signal
       });
+      clearTimeout(timeoutId);
       if (response.ok || response.status >= 400 && response.status < 500) {
         await this.storage.remove(reqToSync.id);
         console.log(`[Axiom] Request ${reqToSync.id} synced successfully.`);
@@ -70,6 +81,7 @@ var SyncManager = class {
         await this.handleFailure(reqToSync);
       }
     } catch (error) {
+      clearTimeout(timeoutId);
       await this.handleFailure(reqToSync);
     }
   }
@@ -78,7 +90,7 @@ var SyncManager = class {
    */
   async handleFailure(request) {
     request.retryCount += 1;
-    const maxRetries = this.config.maxRetries || 3;
+    const maxRetries = this.config.maxRetries ?? 3;
     if (request.retryCount >= maxRetries) {
       console.warn(`[Axiom] Request ${request.id} failed ${maxRetries} times. Moving to Dead Letter.`);
       await this.storage.remove(request.id);
@@ -98,7 +110,10 @@ var AxiomEngine = class {
     this.storage = new MemoryStorageAdapter();
   }
   /**
-   * Initializes the Axiom engine with your specific rules and storage.
+   * Initializes the Axiom engine with global configuration and a storage adapter.
+   * This must be called before making any requests to enable persistence.
+   * * @param config - Global configuration (baseURL, timeouts, custom headers, etc.)
+   * @param storageAdapter - Optional custom adapter (e.g., MMKV). Defaults to in-memory storage.
    */
   create(config, storageAdapter) {
     this.config = config;
@@ -107,6 +122,10 @@ var AxiomEngine = class {
     }
     this.syncManager = new SyncManager(this.storage, this.config);
   }
+  /**
+   * Manually triggers the background sync manager to flush all pending queued requests.
+   * Note: This is automatically handled by `AxiomProvider` when the network reconnects.
+   */
   async forceSync() {
     if (!this.syncManager) {
       console.error("[Axiom] Engine not initialized. Call axiom.create() first.");
@@ -115,59 +134,94 @@ var AxiomEngine = class {
     await this.syncManager.flushQueue();
   }
   /**
-   * Generates a unique ID for queued requests.
+   * Generates a unique collision-resistant ID for queued requests.
    */
   generateId() {
     return Math.random().toString(36).substring(2, 15) + Date.now().toString(36);
   }
   /**
-   * The core POST method. 
+   * Executes an HTTP GET request. 
+   * If the network is unavailable or times out, the request is safely queued.
+   * * @param url - The endpoint URL (appended to baseURL if configured).
+   * @param options - Request-specific options (priority lanes, timeout overrides).
+   * @returns A promise resolving to the response data, status code, and queue state.
+   */
+  async get(url, options) {
+    return this.prepareRequest("GET", url, void 0, options);
+  }
+  /**
+   * Executes an HTTP POST request.
+   * If the network is unavailable or times out, the payload is safely queued.
+   * * @param url - The endpoint URL.
+   * @param data - The payload object to be serialized and sent.
+   * @param options - Request-specific options.
    */
   async post(url, data, options) {
-    const fullUrl = this.config.baseURL ? `${this.config.baseURL}${url}` : url;
-    const request = {
-      id: this.generateId(),
-      timestamp: Date.now(),
-      url: fullUrl,
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        ...this.config.defaultHeaders || {}
-      },
-      body: data ? JSON.stringify(data) : void 0,
-      priority: options?.priority || "urgent",
-      retryCount: 0
-    };
-    return this.attemptFetch(request);
+    return this.prepareRequest("POST", url, data, options);
   }
-  /** The core GET method.
-   * Note: GET requests typically don't have a body, but we still want to queue them if offline.
+  /**
+   * Executes an HTTP PUT request to entirely replace a resource.
+   * * @param url - The endpoint URL.
+   * @param data - The payload object to be serialized and sent.
+   * @param options - Request-specific options.
    */
-  async get(url, options) {
+  async put(url, data, options) {
+    return this.prepareRequest("PUT", url, data, options);
+  }
+  /**
+   * Executes an HTTP PATCH request to partially update a resource.
+   * * @param url - The endpoint URL.
+   * @param data - The partial payload object to be serialized and sent.
+   * @param options - Request-specific options.
+   */
+  async patch(url, data, options) {
+    return this.prepareRequest("PATCH", url, data, options);
+  }
+  /**
+   * Executes an HTTP DELETE request.
+   * * @param url - The endpoint URL.
+   * @param options - Request-specific options.
+   */
+  async delete(url, options) {
+    return this.prepareRequest("DELETE", url, void 0, options);
+  }
+  /**
+   * Internal helper to consolidate request preparation and keep the engine DRY.
+   */
+  async prepareRequest(method, url, data, options) {
     const fullUrl = this.config.baseURL ? `${this.config.baseURL}${url}` : url;
+    const headers = { ...this.config.defaultHeaders || {} };
+    if (options?.headers) {
+      Object.assign(headers, options.headers);
+    }
     const request = {
       id: this.generateId(),
       timestamp: Date.now(),
       url: fullUrl,
-      method: "GET",
-      headers: {
-        ...this.config.defaultHeaders || {}
-      },
+      method,
+      headers,
+      body: data ? JSON.stringify(data) : void 0,
       priority: options?.priority || "urgent",
       retryCount: 0
     };
-    return this.attemptFetch(request);
+    const timeoutMs = options?.timeout || this.config.timeout || 8e3;
+    return this.attemptFetch(request, timeoutMs);
   }
   /**
    * Internal logic to fire the request or catch the network drop.
+   * Handles timeout cancellations via AbortController.
    */
-  async attemptFetch(request) {
+  async attemptFetch(request, timeoutMs) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
     try {
       const response = await fetch(request.url, {
         method: request.method,
         headers: request.headers,
-        body: request.body
+        body: request.body,
+        signal: controller.signal
       });
+      clearTimeout(timeoutId);
       if (response.ok) {
         const responseData = await response.json().catch(() => null);
         return { data: responseData, status: response.status, isQueued: false };
@@ -177,12 +231,16 @@ var AxiomEngine = class {
       }
       return { status: response.status, isQueued: false };
     } catch (error) {
+      clearTimeout(timeoutId);
+      if (error.name === "AbortError") {
+        console.warn(`[Axiom] Request to ${request.url} timed out after ${timeoutMs}ms. Queuing for retry.`);
+      }
       await this.enqueueRequest(request);
       return { status: 202, isQueued: true };
     }
   }
   /**
-   * Saves the request to whatever storage adapter was provided on startup.
+   * Saves the request to the configured storage adapter.
    */
   async enqueueRequest(request) {
     console.warn(`[Axiom] Network unreachable. Queuing request ${request.id}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jayethian/axiom",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "maintainers": [
     "Jayetheus"
   ],

package/src/engine/fetcher.ts

@@ -1,4 +1,4 @@
-import { AxiomConfig, QueuedRequest, RequestPriority } from '../types';
+import { AxiomConfig, AxiomRequestOptions, QueuedRequest, RequestPriority } from '../types';
 import { AxiomStorageAdapter } from '../adapters';
 import { MemoryStorageAdapter } from '../adapters/memory';
 import { SyncManager } from './sync';
@@ -9,7 +9,10 @@ export class AxiomEngine {
   private syncManager!: SyncManager;
 
   /**
-   * Initializes the Axiom engine with your specific rules and storage.
+   * Initializes the Axiom engine with global configuration and a storage adapter.
+   * This must be called before making any requests to enable persistence.
+   * * @param config - Global configuration (baseURL, timeouts, custom headers, etc.)
+   * @param storageAdapter - Optional custom adapter (e.g., MMKV). Defaults to in-memory storage.
    */
   public create(config: AxiomConfig, storageAdapter?: AxiomStorageAdapter): void {
     this.config = config;
@@ -20,6 +23,10 @@ export class AxiomEngine {
     this.syncManager = new SyncManager(this.storage, this.config);
   }
 
+  /**
+   * Manually triggers the background sync manager to flush all pending queued requests.
+   * Note: This is automatically handled by `AxiomProvider` when the network reconnects.
+   */
   public async forceSync(): Promise<void> {
     if (!this.syncManager) {
       console.error("[Axiom] Engine not initialized. Call axiom.create() first.");
@@ -29,98 +36,157 @@ export class AxiomEngine {
   }
 
   /**
-   * Generates a unique ID for queued requests.
+   * Generates a unique collision-resistant ID for queued requests.
    */
   private generateId(): string {
     return Math.random().toString(36).substring(2, 15) + Date.now().toString(36);
   }
 
   /**
-   * The core POST method. 
+   * Executes an HTTP GET request. 
+   * If the network is unavailable or times out, the request is safely queued.
+   * * @param url - The endpoint URL (appended to baseURL if configured).
+   * @param options - Request-specific options (priority lanes, timeout overrides).
+   * @returns A promise resolving to the response data, status code, and queue state.
+   */
+  public async get<T>(
+    url: string, 
+    options?: AxiomRequestOptions
+  ): Promise<{ data?: T; status: number; isQueued: boolean }> {
+    return this.prepareRequest<T>('GET', url, undefined, options);
+  }
+
+  /**
+   * Executes an HTTP POST request.
+   * If the network is unavailable or times out, the payload is safely queued.
+   * * @param url - The endpoint URL.
+   * @param data - The payload object to be serialized and sent.
+   * @param options - Request-specific options.
    */
   public async post<T>(
     url: string, 
     data?: any, 
-    options?: { priority?: RequestPriority }
+    options?: AxiomRequestOptions
   ): Promise<{ data?: T; status: number; isQueued: boolean }> {
-    
-    const fullUrl = this.config.baseURL ? `${this.config.baseURL}${url}` : url;
-    
-    const request: QueuedRequest = {
-      id: this.generateId(),
-      timestamp: Date.now(),
-      url: fullUrl,
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        ...(this.config.defaultHeaders || {})
-      },
-      body: data ? JSON.stringify(data) : undefined,
-      priority: options?.priority || 'urgent',
-      retryCount: 0
-    };
+    return this.prepareRequest<T>('POST', url, data, options);
+  }
+
+  /**
+   * Executes an HTTP PUT request to entirely replace a resource.
+   * * @param url - The endpoint URL.
+   * @param data - The payload object to be serialized and sent.
+   * @param options - Request-specific options.
+   */
+  public async put<T>(
+    url: string, 
+    data?: any, 
+    options?: AxiomRequestOptions
+  ): Promise<{ data?: T; status: number; isQueued: boolean }> {
+    return this.prepareRequest<T>('PUT', url, data, options);
+  }
 
-    return this.attemptFetch<T>(request);
+  /**
+   * Executes an HTTP PATCH request to partially update a resource.
+   * * @param url - The endpoint URL.
+   * @param data - The partial payload object to be serialized and sent.
+   * @param options - Request-specific options.
+   */
+  public async patch<T>(
+    url: string, 
+    data?: any, 
+    options?: AxiomRequestOptions
+  ): Promise<{ data?: T; status: number; isQueued: boolean }> {
+    return this.prepareRequest<T>('PATCH', url, data, options);
   }
 
-  /** The core GET method.
-   * Note: GET requests typically don't have a body, but we still want to queue them if offline.
+  /**
+   * Executes an HTTP DELETE request.
+   * * @param url - The endpoint URL.
+   * @param options - Request-specific options.
    */
-  public async get<T>(
+  public async delete<T>(
     url: string, 
-    options?: { priority?: RequestPriority }
+    options?: AxiomRequestOptions
+  ): Promise<{ data?: T; status: number; isQueued: boolean }> {
+    return this.prepareRequest<T>('DELETE', url, undefined, options);
+  }
+
+  /**
+   * Internal helper to consolidate request preparation and keep the engine DRY.
+   */
+  private async prepareRequest<T>(
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH',
+    url: string,
+    data?: any,
+    options?: AxiomRequestOptions
   ): Promise<{ data?: T; status: number; isQueued: boolean }> {
-    
     const fullUrl = this.config.baseURL ? `${this.config.baseURL}${url}` : url;
     
+    const headers: Record<string, string> = { ...(this.config.defaultHeaders || {}) };
+    if (options?.headers) {
+      Object.assign(headers, options.headers);
+    }
+    
     const request: QueuedRequest = {
       id: this.generateId(),
       timestamp: Date.now(),
       url: fullUrl,
-      method: 'GET',
-      headers: {
-        ...(this.config.defaultHeaders || {})
-      },
+      method,
+      headers,
+      body: data ? JSON.stringify(data) : undefined,
       priority: options?.priority || 'urgent',
       retryCount: 0
     };
 
-    return this.attemptFetch<T>(request);
+    const timeoutMs = options?.timeout || this.config.timeout || 8000;
+
+    return this.attemptFetch<T>(request, timeoutMs);
   }
 
   /**
    * Internal logic to fire the request or catch the network drop.
+   * Handles timeout cancellations via AbortController.
    */
-  private async attemptFetch<T>(request: QueuedRequest): Promise<{ data?: T; status: number; isQueued: boolean }> {
+  private async attemptFetch<T>(request: QueuedRequest, timeoutMs: number): Promise<{ data?: T; status: number; isQueued: boolean }> {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
     try {
       const response = await fetch(request.url, {
         method: request.method,
         headers: request.headers,
-        body: request.body
+        body: request.body,
+        signal: controller.signal
       });
 
+      clearTimeout(timeoutId);
+
       if (response.ok) {
         const responseData = await response.json().catch(() => null);
         return { data: responseData, status: response.status, isQueued: false };
       }
 
-
       if (response.status >= 500) {
         throw new Error('Server Error');
       }
 
-
       return { status: response.status, isQueued: false };
 
-    } catch (error) {
-      await this.enqueueRequest(request);
+    } catch (error: any) {
+        clearTimeout(timeoutId);
+
+        if(error.name === 'AbortError') {
+          console.warn(`[Axiom] Request to ${request.url} timed out after ${timeoutMs}ms. Queuing for retry.`);
+        }
+        
+        await this.enqueueRequest(request);
 
-      return { status: 202, isQueued: true };
+        return { status: 202, isQueued: true };
     }
   }
 
   /**
-   * Saves the request to whatever storage adapter was provided on startup.
+   * Saves the request to the configured storage adapter.
    */
   private async enqueueRequest(request: QueuedRequest): Promise<void> {
     console.warn(`[Axiom] Network unreachable. Queuing request ${request.id}`);

package/src/engine/sync.ts

@@ -11,9 +11,9 @@ export class SyncManager {
 
   /**
    * The master trigger. Call this when the OS reports network is back online.
+   * Automatically sorts requests so 'urgent' items bypass 'background' items.
    */
   public async flushQueue(): Promise<void> {
-    // Prevent overlapping syncs if the network toggles rapidly
     if (this.isSyncing) return;
     this.isSyncing = true;
 
@@ -21,14 +21,20 @@ export class SyncManager {
       const pending = await this.storage.getAll();
       
       if (pending.length === 0) {
-        this.isSyncing = false;
         return;
       }
 
       console.log(`[Axiom] Network restored. Syncing ${pending.length} queued requests...`);
 
-      // We process sequentially to maintain the order of user actions
-      for (const request of pending) {
+      // MITIGATION 3: Priority Lanes (Urgent requests jump the line)
+      // If priorities match, it falls back to timestamp (FIFO) to maintain action order.
+      const sortedQueue = pending.sort((a, b) => {
+        if (a.priority === 'urgent' && b.priority !== 'urgent') return -1;
+        if (a.priority !== 'urgent' && b.priority === 'urgent') return 1;
+        return a.timestamp - b.timestamp;
+      });
+
+      for (const request of sortedQueue) {
         await this.processRequest(request);
       }
       
@@ -48,18 +54,27 @@ export class SyncManager {
       try {
         reqToSync = await this.config.onBeforeSync(request);
       } catch (error) {
-        console.error(`[Axiom] onBeforeSync failed for ${request.id}. Skipping.`);
+        console.error(`[Axiom] onBeforeSync failed for ${request.id}. Marking as failure.`);
+        await this.handleFailure(request); // FIX: Ensure we increment retry count if this fails
         return; 
       }
     }
 
+    // Apply the global timeout to background syncing as well
+    const controller = new AbortController();
+    const timeoutMs = this.config.timeout || 10000; // Default 10s for background syncs
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
     try {
       const response = await fetch(reqToSync.url, {
         method: reqToSync.method,
         headers: reqToSync.headers,
-        body: reqToSync.body
+        body: reqToSync.body,
+        signal: controller.signal
       });
 
+      clearTimeout(timeoutId);
+
       // If it's a success OR a permanent 400 error (like bad data), remove it.
       if (response.ok || (response.status >= 400 && response.status < 500)) {
         await this.storage.remove(reqToSync.id);
@@ -69,7 +84,8 @@ export class SyncManager {
         await this.handleFailure(reqToSync);
       }
     } catch (error) {
-      // Network dropped again mid-sync.
+      clearTimeout(timeoutId);
+      // Network dropped again mid-sync or timeout was reached.
       await this.handleFailure(reqToSync);
     }
   }
@@ -79,7 +95,7 @@ export class SyncManager {
    */
   private async handleFailure(request: QueuedRequest): Promise<void> {
     request.retryCount += 1;
-    const maxRetries = this.config.maxRetries || 3;
+    const maxRetries = this.config.maxRetries ?? 3; // Use nullish coalescing so 0 is valid
 
     if (request.retryCount >= maxRetries) {
       console.warn(`[Axiom] Request ${request.id} failed ${maxRetries} times. Moving to Dead Letter.`);

package/src/types.ts

@@ -1,5 +1,10 @@
+/** * Defines how the request should be treated when the queue flushes. 
+ * Urgent requests bypass the background queue entirely if the network is active.
+ */
 export type RequestPriority = 'urgent' | 'background';
 
+/** * Represents a serialized HTTP request frozen in offline storage. 
+ */
 export interface QueuedRequest {
   id: string;
   timestamp: number;
@@ -11,10 +16,30 @@ export interface QueuedRequest {
   retryCount: number;
 }
 
+/** * Global configuration for the Axiom engine initialized on startup. 
+ */
 export interface AxiomConfig {
+  /** The base URL prepended to all request paths. */
   baseURL?: string;
+  /** Global headers applied to every request (e.g., Auth tokens). */
   defaultHeaders?: Record<string, string>;
+  /** The maximum number of times a queued request will attempt to sync before failing permanently. */
   maxRetries?: number;
+  /** Global timeout in milliseconds before a request is aborted and queued. */
+  timeout?: number;
+  /** Middleware hook triggered immediately before a queued request is synced. Ideal for refreshing Auth tokens. */
   onBeforeSync?: (request: QueuedRequest) => Promise<QueuedRequest>;
+  /** Callback triggered when a request exceeds maxRetries and is permanently removed from the queue. */
   onDeadLetter?: (request: QueuedRequest, error: Error) => void;
+}
+
+/** * Per-request configuration options that override the global configuration. 
+ */
+export interface AxiomRequestOptions {
+  /** Overrides the queue sorting behavior for this specific request. */
+  priority?: RequestPriority;
+  /** Overrides the global timeout limit for this specific request. */
+  timeout?: number;
+  /** Specific headers to append to this single request (e.g., custom Content-Type). */
+  headers?: Record<string, string>;
 }