@adukiorg/anza 0.2.0

package/src/core/api/retry.js

@@ -0,0 +1,69 @@
+/**
+ * src/core/api/retry.js
+ *
+ * Implements exponential backoff with jitter for transient errors.
+ * Ensures the network layer is self-healing for temporary disconnects/server errors,
+ * while instantly failing client-side (4xx) errors.
+ *
+ * Source: doc 11 — Networking §8
+ */
+
+import { PlatformError } from './fetch.js';
+
+/**
+ * Retries an asynchronous operation with exponential backoff and full jitter.
+ */
+export async function retry(operation, options = {}) {
+  const {
+    attempts = 3,
+    base = 100, // starting delay in ms
+    maxDelay = 3000, // maximum wait time in ms
+    signal
+  } = options;
+
+  let attempt = 0;
+
+  while (true) {
+    if (signal?.aborted) {
+      throw new PlatformError({
+        code: 'NETWORK_ERROR',
+        message: 'Network request aborted before retry attempt',
+        recoverable: false
+      });
+    }
+
+    try {
+      return await operation();
+    } catch (err) {
+      attempt++;
+
+      // Qualify transient failure: Network dropouts, timeouts, or server (5xx) issues
+      const isTransient = err.code === 'NETWORK_TIMEOUT' ||
+                          err.code === 'NETWORK_ERROR' ||
+                          (err.code === 'HTTP_ERROR' && err.context?.status >= 500);
+
+      if (attempt >= attempts || !isTransient) {
+        throw err;
+      }
+
+      // Exponential backoff with full jitter calculation
+      const tempDelay = base * Math.pow(2, attempt);
+      const delay = Math.random() * Math.min(maxDelay, tempDelay);
+
+      await new Promise((resolve, reject) => {
+        const timeoutId = setTimeout(resolve, delay);
+
+        if (signal) {
+          signal.addEventListener('abort', () => {
+            clearTimeout(timeoutId);
+            reject(new PlatformError({
+              code: 'NETWORK_ERROR',
+              message: 'Network request aborted during retry backoff',
+              recoverable: false
+            }));
+          });
+        }
+      });
+    }
+  }
+}

package/src/core/api/stream.js

@@ -0,0 +1,127 @@
+/**
+ * src/core/api/stream.js
+ *
+ * Implements Streams API and progressive response handling.
+ * Parses NDJSON streams using native TransformStream pipelines, preserving backpressure.
+ * Useful for large data lists, logs, or live AI streaming responses.
+ *
+ * Source: doc 11 — Networking §11
+ */
+
+/**
+ * Creates a reusable TransformStream to parse Newline-Delimited JSON (NDJSON).
+ */
+export function createNDJSONTransform() {
+  let buffer = '';
+  return new TransformStream({
+    transform(chunk, controller) {
+      buffer += chunk;
+      const lines = buffer.split('\n');
+      buffer = lines.pop() || ''; // Keep trailing fragment in buffer
+
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed) {
+          try {
+            controller.enqueue(JSON.parse(trimmed));
+          } catch (err) {
+            controller.error(new Error(`Failed to parse NDJSON line: ${err.message}`));
+          }
+        }
+      }
+    },
+    flush(controller) {
+      const trimmed = buffer.trim();
+      if (trimmed) {
+        try {
+          controller.enqueue(JSON.parse(trimmed));
+        } catch (err) {
+          controller.error(new Error(`Failed to parse NDJSON line on flush: ${err.message}`));
+        }
+      }
+    }
+  });
+}
+
+import { events } from './events/index.js';
+
+/**
+ * Initiates a streaming request and yields parsed JSON chunks as an AsyncIterable.
+ */
+export async function* stream(url, opts = {}) {
+  const { signal, ...fetchOpts } = opts;
+
+  // Generate unique request ID to scope streaming telemetry events
+  const requestId = opts.requestId || (typeof crypto !== 'undefined' && crypto.randomUUID
+    ? crypto.randomUUID()
+    : Math.random().toString(36).slice(2) + Date.now().toString(36));
+
+  // Register request-specific temporary listeners
+  const disposes = [];
+  if (opts.on && typeof opts.on === 'object') {
+    for (const [event, handler] of Object.entries(opts.on)) {
+      if (typeof handler === 'function') {
+        const dispose = events.on(event, (e) => {
+          if (e.detail?.requestId === requestId) {
+            handler(e);
+          }
+        });
+        disposes.push(dispose);
+      }
+    }
+  }
+
+  let response;
+  try {
+    response = await fetch(url, { ...fetchOpts, signal });
+  } catch (err) {
+    events.emit('error', { error: err, requestId });
+    events.emit('failed', { error: err, requestId });
+    throw err;
+  }
+
+  if (!response.ok) {
+    const err = new Error(`Streaming failed: HTTP ${response.status} ${response.statusText}`);
+    events.emit('status:' + response.status, { response, requestId });
+    events.emit('failed', { response, requestId });
+    events.emit('error', { error: err, requestId });
+    throw err;
+  }
+
+  if (!response.body) {
+    const err = new Error('Streaming failed: Response body is not readable');
+    events.emit('error', { error: err, requestId });
+    throw err;
+  }
+
+  const reader = response.body
+    .pipeThrough(new TextDecoderStream())
+    .pipeThrough(createNDJSONTransform())
+    .getReader();
+
+  try {
+    while (true) {
+      let result;
+      try {
+        result = await reader.read();
+      } catch (err) {
+        events.emit('error', { error: err, requestId });
+        throw err;
+      }
+
+      const { value, done } = result;
+      if (done) break;
+
+      // Emit chunk telemetry event locally and globally
+      events.emit('chunk', { chunk: value, requestId });
+
+      yield value;
+    }
+  } finally {
+    reader.releaseLock();
+    // Guarantee auto-cleanup of streaming listeners
+    for (const dispose of disposes) {
+      dispose();
+    }
+  }
+}

package/src/core/api/upload.js

@@ -0,0 +1,180 @@
+/**
+ * src/core/api/upload.js
+ *
+ * Handles file uploads with real-time progress events.
+ * Uses standard XMLHttpRequest to provide precise progress callbacks (opts.onProgress),
+ * bridging the standard fetch upload progress gap in Baseline browsers.
+ *
+ * Source: doc 11 — Networking §14
+ */
+
+import { PlatformError } from './fetch.js';
+import { events } from './events/index.js';
+
+/**
+ * Uploads a file or binary payload with progress tracking and AbortSignal support.
+ */
+export function upload(url, fileOrData, opts = {}) {
+  const {
+    method = 'POST',
+    headers = {},
+    onProgress,
+    signal
+  } = opts;
+
+  // Generate unique request ID to scope uploading telemetry events
+  const requestId = opts.requestId || (typeof crypto !== 'undefined' && crypto.randomUUID
+    ? crypto.randomUUID()
+    : Math.random().toString(36).slice(2) + Date.now().toString(36));
+
+  // Register request-specific temporary listeners
+  const disposes = [];
+  if (opts.on && typeof opts.on === 'object') {
+    for (const [event, handler] of Object.entries(opts.on)) {
+      if (typeof handler === 'function') {
+        const dispose = events.on(event, (e) => {
+          if (e.detail?.requestId === requestId) {
+            handler(e);
+          }
+        });
+        disposes.push(dispose);
+      }
+    }
+  }
+
+  const cleanup = () => {
+    for (const dispose of disposes) {
+      dispose();
+    }
+  };
+
+  return new Promise((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    xhr.open(method, url, true);
+
+    // Apply headers
+    for (const [key, value] of Object.entries(headers)) {
+      xhr.setRequestHeader(key, value);
+    }
+
+    // Attach upload progress listeners
+    if (xhr.upload) {
+      xhr.upload.onprogress = (event) => {
+        if (event.lengthComputable) {
+          const progressPayload = {
+            loaded: event.loaded,
+            total: event.total,
+            percentage: Math.round((event.loaded / event.total) * 100)
+          };
+
+          // Trigger legacy onProgress callback if defined
+          if (onProgress) {
+            onProgress(progressPayload);
+          }
+
+          // Emit progress telemetry event
+          events.emit('progress', { ...progressPayload, requestId });
+        }
+      };
+    }
+
+    // Handle abort triggers
+    if (signal) {
+      if (signal.aborted) {
+        xhr.abort();
+        cleanup();
+        return reject(
+          new PlatformError({
+            code: 'NETWORK_ERROR',
+            message: 'Upload aborted',
+            recoverable: false
+          })
+        );
+      }
+      signal.addEventListener('abort', () => {
+        xhr.abort();
+        cleanup();
+        reject(
+          new PlatformError({
+            code: 'NETWORK_ERROR',
+            message: 'Upload aborted',
+            recoverable: false
+          })
+        );
+      });
+    }
+
+    xhr.onload = () => {
+      if (xhr.status >= 200 && xhr.status < 300) {
+        let responseData = xhr.responseText;
+        try {
+          responseData = JSON.parse(responseData);
+        } catch {
+          // Keep raw text if not JSON format
+        }
+
+        // Mock a simple Response object for matching response event payloads
+        const mockResponse = {
+          status: xhr.status,
+          ok: true,
+          headers: new Headers({ 'Content-Type': xhr.getResponseHeader('Content-Type') || 'text/plain' })
+        };
+        events.emit(`status:${xhr.status}`, { response: mockResponse, requestId });
+
+        cleanup();
+        resolve(responseData);
+      } else {
+        const err = new PlatformError({
+          code: 'HTTP_ERROR',
+          message: `Upload failed with status code ${xhr.status}`,
+          context: { url, status: xhr.status },
+          recoverable: xhr.status >= 500
+        });
+
+        const mockResponse = {
+          status: xhr.status,
+          ok: false,
+          headers: new Headers({ 'Content-Type': xhr.getResponseHeader('Content-Type') || 'text/plain' })
+        };
+        events.emit(`status:${xhr.status}`, { response: mockResponse, requestId });
+        events.emit('failed', { response: mockResponse, requestId });
+        events.emit('error', { error: err, requestId });
+
+        cleanup();
+        reject(err);
+      }
+    };
+
+    xhr.onerror = (err) => {
+      const errorObj = new PlatformError({
+        code: 'NETWORK_ERROR',
+        message: 'Upload network connection failed',
+        cause: err,
+        context: { url },
+        recoverable: true
+      });
+      events.emit('failed', { error: errorObj, requestId });
+      events.emit('error', { error: errorObj, requestId });
+
+      cleanup();
+      reject(errorObj);
+    };
+
+    xhr.ontimeout = () => {
+      const errorObj = new PlatformError({
+        code: 'NETWORK_TIMEOUT',
+        message: 'Upload request timed out',
+        context: { url },
+        recoverable: true
+      });
+      events.emit('timeout', { error: errorObj, requestId });
+      events.emit('failed', { error: errorObj, requestId });
+      events.emit('error', { error: errorObj, requestId });
+
+      cleanup();
+      reject(errorObj);
+    };
+
+    xhr.send(fileOrData);
+  });
+}

package/src/core/api/usage.md

@@ -0,0 +1,206 @@
+# Networking & Caching Layer Usage Guide (`core.api`)
+
+The `core.api` networking layer is a baseline-native, local-first HTTP client designed for high performance, self-healing retries, dynamic prefix routing, telemetry-driven event hooks, and fine-grained TTL caching.
+
+---
+
+## 1. Quick Start
+
+Import the client directly from the ESM entry point:
+
+```javascript
+import { api } from '@adukiorg/anza/api';
+
+// Simple GET request (automatically parses JSON)
+const profile = await api.get('/user/profile');
+console.log(profile.name);
+
+// Simple POST request with body serialization
+const result = await api.post('/posts', { title: 'Native ESM rules' });
+```
+
+---
+
+## 2. Dynamic Outbound Prefix Resolution
+
+Prefixes let you map short names or sub-paths to base URLs exactly once at application bootstrap. This keeps your request endpoints clean and isolates environment configuration.
+
+### Registering Prefixes
+
+```javascript
+import { api } from '@adukiorg/anza/api';
+
+// Add configuration at startup
+api.prefix.add('auth', 'https://auth.example.com');
+api.prefix.add('default', 'https://api.example.com'); // acts as root fallback
+```
+
+### Automatic Path Resolution
+
+The client automatically detects prefixes and safely concatenates paths without duplicating slashes:
+
+```javascript
+// Resolves to: https://auth.example.com/login
+const token = await api.post('auth/login', { username, password });
+
+// Resolves to root fallback: https://api.example.com/user/profile
+const profile = await api.get('/user/profile');
+
+// Fully qualified URLs are left unchanged
+const data = await api.get('https://other-domain.org/data');
+```
+
+---
+
+## 3. Fine-Grained TTL Caching
+
+Caching in `core.api` defaults to a **zero-cache policy** (network-only) unless an explicit expiry/TTL is provided. This prevents dynamic state mutations from serving stale data by default.
+
+### Caching with TTL
+
+To cache successful GET responses, pass `expiry` or `ttl` (in milliseconds) inside request options:
+
+```javascript
+// Cache is checked first. On miss, network is called and cache is populated for 60 seconds
+const products = await api.get('/products', { expiry: 60000 });
+```
+
+### Cache Purging & Glob Invalidation
+
+The cache manager supports granular deletions, whole store purges, or namespace-level invalidation utilizing standard glob patterns:
+
+```javascript
+// Purge the entire API cache store
+await api.cache.clear();
+
+// Evict a single exact URL
+await api.cache.delete('https://api.example.com/products');
+
+// Glob Purging: Evict all endpoints starting with or containing /user/
+await api.cache.delete('*/user/*');
+```
+
+---
+
+## 4. Telemetry Events & Network Monitoring
+
+The networking layer streams real-time connection events, allowing you to attach global hooks, security checks, and toast alerts based on HTTP statuses, content types, or failures.
+
+### Standard Telemetry Events
+
+| Event Name | Trigger |
+| --- | --- |
+| `'error'` | Any network connection failure, request timeout, or server error |
+| `'failed'` | Any non-ok response status (>= 400) or aborted connections |
+| `'timeout'` | Requests exceeding their defined timeout limit |
+| `'status:401'` | Specific HTTP 401 Unauthorized responses |
+| `'status:500'` | Specific HTTP 500 Internal Server Error responses |
+| `'status:xxx'` | Any specific HTTP status code (replace `xxx` with the desired code) |  
+| `'type:text'` | Successful responses carrying `text/plain` Content-Type |
+| `'type:json'` | Successful responses carrying `application/json` Content-Type |
+| `'type:stream'` | Successful responses carrying `text/event-stream` Content-Type |
+
+### Request-Scoped Event Listeners (Automatic Cleanup)
+
+If you only care about events triggered by a **specific network request**, you can define listeners directly in the request options using the `on` object. The API client scopes these listeners to this single request and **automatically cleans them up** as soon as the request terminates (succeeds or fails). No manual disposer calls are needed:
+
+```javascript
+await api.get('/user/profile', {
+  on: {
+    // Fired only if this specific request returns a 401
+    'status:401': () => {
+      redirectToLogin();
+    },
+    // Fired only if this specific request fails or times out
+    'failed': (event) => {
+      console.error('Request failed:', event.detail.error);
+    }
+  }
+});
+```
+
+### Global Listeners & Manual Disposers
+
+For broad application state hooks (such as global loading spinners or error overlays), subscribe to events globally. The `api.on` method returns a synchronous disposer function to stop listening:
+
+```javascript
+// Register a global listener and receive a clean unsubscription function
+const offUnauthorized = api.on('status:401', (event) => {
+  redirectToLogin();
+});
+
+// To stop listening manually, simply invoke the returned function:
+offUnauthorized();
+```
+
+### Advanced Lifecycle-Gated Cleaning (with AbortSignal)
+
+If you are developing custom elements or reactive components, you can pass an `AbortSignal` as the third parameter to `api.on`. The networking engine will listen to the signal and **automatically clean up the listener** when the component unmounts or aborts, eliminating boilerplate disposer calls:
+
+```javascript
+// Example inside a reactive Custom Element mount hook:
+mount({ el, ctrl }) {
+  // Pass the element's mount AbortController signal
+  api.on('status:401', () => {
+    redirectToLogin();
+  }, ctrl.signal);
+  
+  // Fully automated: detaches completely when the component unmounts!
+}
+```
+
+---
+
+## 5. Streaming & Progress Uploads
+
+### Response Streams (NDJSON)
+
+For live logs or AI streaming responses, the client parses newline-delimited JSON streams natively preserving backpressure. It fully supports request-scoped `on` listeners (e.g. `chunk`, `error`, `failed`) and broadcasts them to the global telemetry bus with automatic unsubscriptions:
+
+```javascript
+// Stream lines as an AsyncIterable and hook event listeners directly
+const eventStream = api.stream('https://api.example.com/logs/stream', {
+  on: {
+    // Triggers progressively for each enqueued JSON chunk
+    chunk: (event) => {
+      console.log('Progressive chunk:', event.detail.chunk);
+    },
+    // Triggers if the connection drops mid-stream
+    error: (event) => {
+      console.error('Stream dropped:', event.detail.error);
+    }
+  }
+});
+
+for await (const chunk of eventStream) {
+  // Yields parsed JSON chunks symmetrically
+}
+```
+
+### Tracking Upload Progress
+
+Standard `fetch` uploads do not support progress callbacks in Baseline browsers. The client bridges this gap utilizing a highly precise native XMLHttpRequest gateway. It fully supports request-scoped `on` listeners—enabling clean tracking of upload `progress`, HTTP `status`, success, or `error` events:
+
+```javascript
+const fileData = new FormData();
+fileData.append('file', rawFileBlob);
+
+const response = await api.upload('https://api.example.com/upload', fileData, {
+  method: 'POST',
+  on: {
+    // Fired progressively during transmission
+    progress: (event) => {
+      const { loaded, total, percentage } = event.detail;
+      console.log(`Uploaded: ${loaded} / ${total} (${percentage}%)`);
+    },
+    // Fired on successful completion
+    'status:200': (event) => {
+      console.log('Upload completed successfully!');
+    },
+    // Fired on connection errors
+    error: (event) => {
+      console.error('Upload failed:', event.detail.error);
+    }
+  }
+});
+```

package/src/core/events/bus.js

@@ -0,0 +1,38 @@
+/**
+ * src/core/events/bus.js
+ *
+ * Global Event Bus.
+ * Extends the native EventTarget for engine-optimized listener dispatch.
+ * Preserves backward-compatible .on() and .emit() wrapper methods while
+ * exposing the full native addEventListener / dispatchEvent interface.
+ *
+ * Source: doc 10 — Event Architecture §9
+ */
+
+export class EventBus extends EventTarget {
+  /**
+   * Subscribes to a global event.
+   * If a signal is provided, the subscription is automatically cleaned up when the signal aborts.
+   * Returns a disposer function for manual cleanup.
+   */
+  on(type, fn, signal) {
+    if (signal?.aborted) return () => {};
+
+    this.addEventListener(type, fn, { signal });
+
+    const dispose = () => {
+      this.removeEventListener(type, fn);
+    };
+
+    return dispose;
+  }
+
+  /**
+   * Dispatches a global custom event with a detail payload.
+   */
+  emit(type, detail) {
+    this.dispatchEvent(new CustomEvent(type, { detail }));
+  }
+}
+
+export const bus = new EventBus();

package/src/core/events/delegate.js

@@ -0,0 +1,79 @@
+/**
+ * src/core/events/delegate.js
+ *
+ * High-performance event delegation with fast-path selector matching.
+ * Handles dynamic delegation of events traversing Shadow DOM boundaries
+ * by evaluating event.composedPath(), caching matcher evaluations in a WeakMap.
+ *
+ * Source: doc 10 — Event Architecture §6
+ */
+
+// Dual-layered WeakMap cache to prevent redundant CSS selector evaluations
+const matchesCache = new WeakMap();
+
+/**
+ * Checks if an element matches a selector using cached query evaluations.
+ */
+function matchesSelector(element, selector) {
+  if (!element || typeof element.matches !== 'function') {
+    return false;
+  }
+
+  let selectorMap = matchesCache.get(element);
+  if (!selectorMap) {
+    selectorMap = new Map();
+    matchesCache.set(element, selectorMap);
+  }
+
+  if (selectorMap.has(selector)) {
+    return selectorMap.get(selector);
+  }
+
+  const result = element.matches(selector);
+  selectorMap.set(selector, result);
+  return result;
+}
+
+/**
+ * Attaches a delegated event listener to an ancestor root element.
+ *
+ * @param {EventTarget} root - The root container element.
+ * @param {string} selector - The query selector to match dynamic descendants.
+ * @param {string} type - The event name to intercept.
+ * @param {Function} handler - The listener callback, with `this` bound to the matched element.
+ * @param {Object} [options={}] - Standard addEventListener options.
+ * @returns {Function} A disposer function that unregisters the delegation hook.
+ */
+export function delegate(root, selector, type, handler, options = {}) {
+  const signal = options.signal;
+  if (signal?.aborted) return () => {};
+
+  const listener = (event) => {
+    // composedPath() contains the full bubble chain, traversing through nested shadow trees
+    const path = event.composedPath();
+
+    for (const target of path) {
+      if (target === root) break;
+      if (matchesSelector(target, selector)) {
+        // Invoke handler with matched element bound to `this`
+        handler.call(target, event, target);
+        break;
+      }
+    }
+  };
+
+  root.addEventListener(type, listener, options);
+
+  const dispose = () => {
+    root.removeEventListener(type, listener, options);
+    if (signal) {
+      signal.removeEventListener('abort', dispose);
+    }
+  };
+
+  if (signal) {
+    signal.addEventListener('abort', dispose, { once: true });
+  }
+
+  return dispose;
+}