@jayethian/axiom 0.1.0 → 0.1.2

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,13 +1,35 @@
 {
   "name": "@jayethian/axiom",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "maintainers": [
     "Jayetheus"
   ],
-  "description": "A resilient, offline-first fetch wrapper",
+  "description": "A resilient, offline-first fetch wrapper for React Native & Next.js.",
+  "keywords": [
+    "react-native",
+    "nextjs",
+    "fetch",
+    "axios",
+    "offline-first",
+    "sync",
+    "network",
+    "queue",
+    "indexeddb"
+  ],
+  "homepage": "https://github.com/jayethian/axiom#readme",
+  "bugs": {
+    "url": "https://github.com/jayethian/axiom/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jayethian/axiom.git"
+  },
   "publishConfig": {
     "access": "public"
   },
+  "files": [
+    "dist"
+  ],
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -28,6 +50,5 @@
   },
   "peerDependencies": {
     "react": ">=17.0.0"
-  },
-  "packageManager": "yarn@4.12.0"
-}
+  }
+}

package/.editorconfig

@@ -1,8 +0,0 @@
-root = true
-
-[*]
-charset = utf-8
-end_of_line = lf
-indent_size = 2
-indent_style = space
-insert_final_newline = true

package/.gitattributes

@@ -1,4 +0,0 @@
-/.yarn/**            linguist-vendored
-/.yarn/releases/*    binary
-/.yarn/plugins/**/*  binary
-/.pnp.*              binary linguist-generated

package/src/adapters/index.ts

@@ -1,15 +0,0 @@
-import { QueuedRequest } from '../types';
-
-export interface AxiomStorageAdapter {
-  /** Saves a request to the persistent queue */
-  save(request: QueuedRequest): Promise<void>;
-  
-  /** Retrieves all pending requests, usually ordered by timestamp */
-  getAll(): Promise<QueuedRequest[]>;
-  
-  /** Removes a specific request after it successfully syncs */
-  remove(id: string): Promise<void>;
-  
-  /** Wipes the queue entirely (useful for user logout) */
-  clearAll(): Promise<void>;
-}

package/src/adapters/memory.ts

@@ -1,22 +0,0 @@
-import { AxiomStorageAdapter } from './index';
-import { QueuedRequest } from '../types';
-
-export class MemoryStorageAdapter implements AxiomStorageAdapter {
-  private queue: Map<string, QueuedRequest> = new Map();
-
-  async save(request: QueuedRequest): Promise<void> {
-    this.queue.set(request.id, request);
-  }
-
-  async getAll(): Promise<QueuedRequest[]> {
-    return Array.from(this.queue.values()).sort((a, b) => a.timestamp - b.timestamp);
-  }
-
-  async remove(id: string): Promise<void> {
-    this.queue.delete(id);
-  }
-
-  async clearAll(): Promise<void> {
-    this.queue.clear();
-  }
-}

package/src/engine/fetcher.ts

@@ -1,131 +0,0 @@
-import { AxiomConfig, QueuedRequest, RequestPriority } from '../types';
-import { AxiomStorageAdapter } from '../adapters';
-import { MemoryStorageAdapter } from '../adapters/memory';
-import { SyncManager } from './sync';
-
-export class AxiomEngine {
-  private config: AxiomConfig = {};
-  private storage: AxiomStorageAdapter = new MemoryStorageAdapter(); 
-  private syncManager!: SyncManager;
-
-  /**
-   * Initializes the Axiom engine with your specific rules and storage.
-   */
-  public create(config: AxiomConfig, storageAdapter?: AxiomStorageAdapter): void {
-    this.config = config;
-    if (storageAdapter) {
-      this.storage = storageAdapter;
-    }
-
-    this.syncManager = new SyncManager(this.storage, this.config);
-  }
-
-  public async forceSync(): Promise<void> {
-    if (!this.syncManager) {
-      console.error("[Axiom] Engine not initialized. Call axiom.create() first.");
-      return;
-    }
-    await this.syncManager.flushQueue();
-  }
-
-  /**
-   * Generates a unique ID for queued requests.
-   */
-  private generateId(): string {
-    return Math.random().toString(36).substring(2, 15) + Date.now().toString(36);
-  }
-
-  /**
-   * The core POST method. 
-   */
-  public async post<T>(
-    url: string, 
-    data?: any, 
-    options?: { priority?: RequestPriority }
-  ): 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.attemptFetch<T>(request);
-  }
-
-  /** The core GET method.
-   * Note: GET requests typically don't have a body, but we still want to queue them if offline.
-   */
-  public async get<T>(
-    url: string, 
-    options?: { priority?: RequestPriority }
-  ): 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: 'GET',
-      headers: {
-        ...(this.config.defaultHeaders || {})
-      },
-      priority: options?.priority || 'urgent',
-      retryCount: 0
-    };
-
-    return this.attemptFetch<T>(request);
-  }
-
-  /**
-   * Internal logic to fire the request or catch the network drop.
-   */
-  private async attemptFetch<T>(request: QueuedRequest): Promise<{ data?: T; status: number; isQueued: boolean }> {
-    try {
-      const response = await fetch(request.url, {
-        method: request.method,
-        headers: request.headers,
-        body: request.body
-      });
-
-      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);
-
-      return { status: 202, isQueued: true };
-    }
-  }
-
-  /**
-   * Saves the request to whatever storage adapter was provided on startup.
-   */
-  private async enqueueRequest(request: QueuedRequest): Promise<void> {
-    console.warn(`[Axiom] Network unreachable. Queuing request ${request.id}`);
-    await this.storage.save(request);
-  }
-}
-
-export const axiom = new AxiomEngine();