🌌 Luminara

Luminara is a modern, universal HTTP client built on native fetch, engineered for developers and teams who demand reliability, scalability, and architectural clarity. It provides full lifecycle control over HTTP requests — from orchestration and interception to retries, deduplication, and analytics — all with zero external dependencies.

Lightweight by design yet powerful in scope, Luminara enables consistent, predictable network behavior across all environments — browsers (React, Vue, Angular, Svelte, vanilla JS) and Node.js 18+. Its domain-driven architecture and type-safe foundation make it ideal for enterprise-grade applications that need transparent debugging, real-time visibility, and extendable control over every request.

🔗 Links

• 🎨 Interactive Sandbox And Documentation Website: luminara.website
• 📦 npm Package: npmjs.com/package/luminara
• 🐙 GitHub Repository: github.com/miller-28/luminara
• ⚡ Performance Benchmarks: luminara.website/benchmark

✨ Features

Core Architecture

• ⚡ Built on modern native fetch - Zero external dependencies
• 🌐 Universal compatibility - Browsers + Node.js 18+ with native fetch
• 🏗️ Framework-agnostic - Works with React, Vue, Angular, Svelte, vanilla JS, and Node.js
• 🏗️ Domain-driven architecture - Feature-based modular structure
• 📦 Dual export support - ESM/CJS compatibility with auto-detection
• 🚗 Extensible driver architecture - Custom drivers via forking
• 💎 Ultra-compact footprint
• 🪶 Zero dependencies - Truly standalone
• 🔄 Same API everywhere - Identical behavior in all environments

Request Lifecycle (Orchestration Layer)

• 🔌 Enhanced interceptor architecture - Deterministic order, mutable context, retry-aware
• 🍪 Plugin system - Extensible architecture with official plugins (cookie-jar)
• 📊 Comprehensive stats system - Real-time metrics, analytics, and query interface
• 📝 Verbose logging system - Detailed debugging and request tracing

Pre-Flight Features (Request Dispatcher - Phase 1)

• 🔄 Request deduplication - Automatic in-flight duplicate request prevention
• ⏱️ Request debouncing - Intelligent request delay with automatic cancellation
• 🚦 Advanced rate limiting - Token bucket algorithm with global, domain, and endpoint scoping

In-Flight Features (Request Execution - Phase 2)

• ⏱️ Configurable timeouts - Request timeouts and abort controller support
• 🔄 Comprehensive retry system - 6 backoff strategies (exponential, fibonacci, jitter, etc.)
• 🏎️ Request hedging - Race and cancel-and-retry policies for latency optimization

Post-Flight Features (Response Handlers - Phase 3)

• 🎯 Response type handling - JSON, text, form data, binary support
• 🛡️ Robust error handling - Comprehensive error categorization and handling

Developer Experience

• 🎯 Fully promise-based with TypeScript support

---

✅ Battle-Tested Reliability

Luminara is validated by a comprehensive test suite covering all features and edge cases:

• ✅ 241 tests across 17 test suites (100% passing)
• 🎯 Programmatic validation - Tests actual behavior, not just API contracts
• 🧪 Framework simulation - React, Vue, Angular usage patterns
• ⏱️ Timing accuracy - Backoff strategies validated to millisecond precision
• 🛡️ Error scenarios - Comprehensive failure case coverage
• 🔄 Integration testing - Feature combinations (retry + timeout + hedging)
• 📊 Real package testing - Tests built distribution, not source files

Test Categories:

• Basic HTTP Operations (8) • Retry Logic (23) • Backoff Strategies (17)
• Request Hedging (24) • Interceptors (12) • Stats System (23)
• Rate Limiting (7) • Debouncing (16) • Deduplication (17)
• Error Handling (21) • Timeouts (11) • Response Types (7)
• Custom Drivers (10) • Edge Cases (15) • Framework Patterns (8)
• Plugins (7)

📋 View Test Documentation • Run Tests Locally

---

📦 Installation

NPM/Yarn (All Frameworks)

# npm
npm install luminara

# yarn
yarn add luminara

# pnpm
pnpm add luminara

CDN (Vanilla JavaScript)

<!-- ES Modules via CDN -->
<script type="module">
  import { createLuminara } from 'https://cdn.skypack.dev/luminara';
  // Your code here
</script>

Framework-Specific Imports

React, Vue, Angular, Svelte (Browser)

import { createLuminara } from 'luminara';

Node.js (ESM)

import { createLuminara } from 'luminara';

const api = createLuminara({
  baseURL: 'https://api.example.com',
  retry: 3,
  timeout: 5000
});

const data = await api.getJson('/users');
console.log(data);

Node.js (CommonJS)

const { createLuminara } = require('luminara');

const api = createLuminara({
  baseURL: 'https://api.example.com'
});

api.getJson('/users')
  .then(data => console.log(data))
  .catch(err => console.error(err));

Vanilla JavaScript (Browser)

import { createLuminara } from 'luminara';

---

🚀 Quick Start

Basic Usage

import { createLuminara } from "luminara";

const api = createLuminara();

// GET JSON
const response = await api.getJson("https://api.example.com/users");
console.log(response.data);

// POST JSON
await api.postJson("https://api.example.com/posts", {
  title: "Hello Luminara",
  content: "A beautiful HTTP client"
});

// GET Text
const textResponse = await api.getText("https://example.com");

// POST Form Data
await api.postForm("https://api.example.com/upload", {
  name: "John",
  email: "john@example.com"
});

// PUT/PATCH with JSON
await api.putJson("https://api.example.com/users/1", { name: "Updated" });
await api.patchJson("https://api.example.com/users/1", { email: "new@example.com" });

// GET XML/HTML/Binary
const xmlResponse = await api.getXml("https://api.example.com/feed.xml");
const htmlResponse = await api.getHtml("https://example.com");
const blobResponse = await api.getBlob("https://api.example.com/file.pdf");
const bufferResponse = await api.getArrayBuffer("https://api.example.com/data.bin");

// NDJSON (Newline Delimited JSON)
const ndjsonResponse = await api.getNDJSON("https://api.example.com/stream");

// Multipart form data
const formData = new FormData();
formData.append('file', fileBlob);
await api.postMultipart("https://api.example.com/upload", formData);

// SOAP requests
await api.postSoap("https://api.example.com/soap", xmlPayload, {
  soapVersion: '1.1' // or '1.2'
});

Configuration

const api = createLuminara({
  baseURL: "https://api.example.com",
  timeout: 10000,
  retry: 3,
  retryDelay: 1000,
  backoffType: "exponential",
  backoffMaxDelay: 30000,
  retryStatusCodes: [408, 429, 500, 502, 503, 504],
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  },
  verbose: true,                // Enable detailed logging
  statsEnabled: true,           // Enable request statistics (default: true)
  ignoreResponseError: false,   // Throw on HTTP errors (default: false)
  responseType: "auto",         // Auto-detect response type
  query: {                      // Default query parameters
    "api_version": "v1"
  }
});

Rate Limiting

Luminara includes advanced rate limiting with token bucket algorithm and flexible scoping:

const api = createLuminara({
  baseURL: "https://api.example.com",
  rateLimit: {
    rps: 10,                   // 10 requests per second
    burst: 20,                 // Allow burst of 20 requests
    scope: 'domain'            // Rate limit per domain
  }
});

// Different scoping options
const globalLimiter = createLuminara({
  rateLimit: {
    rps: 100,
    scope: 'global'            // Single rate limit across all requests
  }
});

const endpointLimiter = createLuminara({
  rateLimit: {
    rps: 5,
    scope: 'endpoint',         // Rate limit per unique endpoint
    include: ['/api/users/*'], // Only apply to specific patterns
    exclude: ['/api/health']   // Exclude certain endpoints
  }
});

// Get rate limiting stats
const rateLimitStats = api.getRateLimitStats();
console.log(rateLimitStats);

// Reset rate limiting stats
api.resetRateLimitStats();

---

📤 Exports & Advanced Usage

Luminara provides multiple export options for different use cases:

Simple Factory (Recommended)

import { createLuminara } from "luminara";

// Creates client with NativeFetchDriver by default
const api = createLuminara({
  baseURL: "https://api.example.com",
  retry: 3,
  backoffType: "exponential"
});

Direct Client & Driver Access

import { 
  LuminaraClient, 
  NativeFetchDriver
} from "luminara";

// Use native fetch driver (default and only driver)
const driver = NativeFetchDriver({
  timeout: 10000,
  retry: 5
});
const api = new LuminaraClient(driver);

Feature Utilities & Constants

import { 
  backoffStrategies,
  createBackoffHandler,
  defaultRetryPolicy,
  createRetryPolicy,
  parseRetryAfter,
  isIdempotentMethod,
  IDEMPOTENT_METHODS,
  DEFAULT_RETRY_STATUS_CODES,
  StatsHub,
  METRIC_TYPES,
  GROUP_BY_DIMENSIONS,
  TIME_WINDOWS
} from "luminara";

// Use backoff strategies directly
const exponentialDelay = backoffStrategies.exponential(3, 1000); // 4000ms

// Create custom retry policy
const customPoli