@adukiorg/anza 0.2.0

package/src/core/api/events/index.js

@@ -0,0 +1,75 @@
+/**
+ * src/core/api/events/index.js
+ *
+ * Performant telemetry event emitter for all API network calls.
+ * Triggers hooks on timeouts, failures, specific HTTP status codes, or response content types.
+ *
+ * Source: doc 11 — Networking §2, core/api/plan.md
+ */
+
+export class ApiEventEmitter {
+  #listeners = new Map();
+
+  /**
+   * Subscribes to a specific network or status event.
+   * Supports lifecycle-gated cleaning using AbortSignal.
+   *
+   * @param {string} event
+   * @param {Function} handler
+   * @param {AbortSignal} [signal]
+   * @returns {Function} Disposer
+   */
+  on(event, handler, signal) {
+    if (signal?.aborted) return () => {};
+
+    if (!this.#listeners.has(event)) {
+      this.#listeners.set(event, new Set());
+    }
+
+    const listener = { handler };
+    this.#listeners.get(event).add(listener);
+
+    let disposed = false;
+    const dispose = () => {
+      if (disposed) return;
+      disposed = true;
+
+      const set = this.#listeners.get(event);
+      if (set) {
+        set.delete(listener);
+        if (set.size === 0) {
+          this.#listeners.delete(event);
+        }
+      }
+    };
+
+    if (signal) {
+      signal.addEventListener('abort', dispose, { once: true });
+    }
+
+    return dispose;
+  }
+
+  /**
+   * Emits a telemetry event with a detail payload.
+   *
+   * @param {string} event
+   * @param {any} detail
+   */
+  emit(event, detail) {
+    const set = this.#listeners.get(event);
+    if (!set) return;
+
+    const apiEvent = { type: event, detail };
+    
+    for (const listener of [...set]) {
+      try {
+        listener.handler(apiEvent);
+      } catch (err) {
+        console.error(`Error in API event listener for "${event}":`, err);
+      }
+    }
+  }
+}
+
+export const events = new ApiEventEmitter();

package/src/core/api/fetch.js

@@ -0,0 +1,99 @@
+/**
+ * src/core/api/fetch.js
+ *
+ * Core fetch wrapper with AbortSignal, timeouts, and browser task priorities.
+ * Maps network and HTTP responses to a standard library-wide error shape.
+ *
+ * Source: doc 11 — Networking §3, §4, §9
+ */
+
+export class PlatformError extends Error {
+  constructor({ code, message, cause, context, recoverable = true }) {
+    super(message);
+    this.name = 'PlatformError';
+    this.code = code;
+    this.cause = cause;
+    this.context = context || {};
+    this.recoverable = recoverable;
+  }
+}
+
+/**
+ * Executes a network fetch request with standard platform enhancements.
+ */
+export async function execute(descriptor) {
+  const {
+    url,
+    timeout = 10000,
+    priority = 'user-visible',
+    signal,
+    ...fetchOpts
+  } = descriptor;
+
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort('timeout'), timeout);
+
+  // Compose signals cleanly (leveraging AbortSignal.any where supported)
+  let activeSignal = controller.signal;
+  if (signal) {
+    if (typeof AbortSignal.any === 'function') {
+      activeSignal = AbortSignal.any([controller.signal, signal]);
+    } else {
+      if (signal.aborted) {
+        controller.abort(signal.reason);
+      } else {
+        signal.addEventListener('abort', () => {
+          controller.abort(signal.reason || 'aborted');
+        });
+      }
+    }
+  }
+
+  const runFetch = async () => {
+    try {
+      const response = await fetch(url, { ...fetchOpts, signal: activeSignal });
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        throw new PlatformError({
+          code: 'HTTP_ERROR',
+          message: `HTTP error ${response.status}: ${response.statusText}`,
+          context: { url, status: response.status, method: fetchOpts.method || 'GET' },
+          recoverable: response.status >= 500
+        });
+      }
+
+      return response;
+    } catch (err) {
+      clearTimeout(timeoutId);
+
+      if (err instanceof PlatformError) throw err;
+
+      const isTimeout = activeSignal.aborted && controller.signal.aborted;
+      throw new PlatformError({
+        code: isTimeout ? 'NETWORK_TIMEOUT' : 'NETWORK_ERROR',
+        message: err.message || (isTimeout ? 'Network request timed out' : 'Network request failed'),
+        cause: err,
+        context: { url, method: fetchOpts.method || 'GET' },
+        recoverable: true
+      });
+    }
+  };
+
+  // Run in browser task scheduler if supported (improves Interaction to Next Paint)
+  if (typeof globalThis.scheduler !== 'undefined' && typeof scheduler.postTask === 'function') {
+    return scheduler.postTask(runFetch, { priority, signal: activeSignal }).catch((err) => {
+      if (err instanceof PlatformError) throw err;
+      const isTimeout = activeSignal.aborted && controller.signal.aborted;
+      throw new PlatformError({
+        code: isTimeout ? 'NETWORK_TIMEOUT' : 'NETWORK_ERROR',
+        message: err.message || (isTimeout ? 'Network request timed out' : 'Network request failed'),
+        cause: err,
+        context: { url, method: fetchOpts.method || 'GET' },
+        recoverable: true
+      });
+    });
+  }
+
+  return runFetch();
+}

package/src/core/api/index.js

@@ -0,0 +1,158 @@
+/**
+ * src/core/api/index.js
+ *
+ * Public networking layer entry point.
+ * Composes request mutators through the outbound/inbound pipeline,
+ * applying caching strategies, transient error retries, and standard timeout controls.
+ *
+ * Source: doc 11 — Networking §2, §4
+ */
+
+import { pipeline } from './pipeline.js';
+import { execute, PlatformError } from './fetch.js';
+import { retry } from './retry.js';
+import { handle as handleCache } from './cache.js';
+import { stream, createNDJSONTransform } from './stream.js';
+import { upload } from './upload.js';
+import { prefixes } from './prefixes/index.js';
+import { events } from './events/index.js';
+import { cache as apiCache } from './caches/index.js';
+
+// Register global telemetry inbound interceptor to emit requests status/errors events
+pipeline.inbound((responseOrError) => {
+  const requestId = responseOrError?.requestId;
+
+  if (responseOrError instanceof Error) {
+    const err = responseOrError;
+    const isTimeout = err.code === 'NETWORK_TIMEOUT';
+    if (isTimeout) {
+      events.emit('timeout', { error: err, requestId });
+    }
+    events.emit('error', { error: err, requestId });
+    events.emit('failed', { error: err, requestId });
+  } else {
+    const response = responseOrError;
+    const status = response.status;
+    
+    events.emit(`status:${status}`, { response, requestId });
+
+    if (!response.ok) {
+      events.emit('failed', { response, requestId });
+      events.emit('error', { response, requestId });
+    } else {
+      const contentType = response.headers.get('Content-Type') || '';
+      if (contentType.includes('application/json')) {
+        events.emit('type:json', { response, requestId });
+      } else if (contentType.includes('text/event-stream')) {
+        events.emit('type:stream', { response, requestId });
+      } else if (contentType.includes('text/')) {
+        events.emit('type:text', { response, requestId });
+      }
+    }
+  }
+  return responseOrError;
+});
+
+/**
+ * Normalizes options and routes the request descriptor through the core pipeline.
+ */
+async function request(url, method, body, opts = {}) {
+  const resolvedUrl = prefixes.resolve(url);
+  const headers = new Headers(opts.headers || {});
+  
+  // Auto-serialize JSON bodies
+  let parsedBody = body;
+  if (body && typeof body === 'object' && !(body instanceof Blob) && !(body instanceof FormData)) {
+    parsedBody = JSON.stringify(body);
+    if (!headers.has('Content-Type')) {
+      headers.set('Content-Type', 'application/json');
+    }
+  }
+
+  // Generate unique request ID to scope request-specific event listeners
+  const requestId = typeof crypto !== 'undefined' && crypto.randomUUID
+    ? crypto.randomUUID()
+    : Math.random().toString(36).slice(2) + Date.now().toString(36);
+
+  const descriptor = {
+    requestId,
+    url: resolvedUrl,
+    method,
+    headers,
+    body: parsedBody,
+    signal: opts.signal,
+    priority: opts.priority || 'user-visible',
+    timeout: opts.timeout || 10000,
+    cache: opts.cache, // cache strategy name: 'cache-first' | 'network-first' | 'stale-while-revalidate'
+    retries: opts.retries ?? 3,
+    ...opts
+  };
+
+  // Register request-specific temporary listeners with automatic scoped cleanup
+  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);
+      }
+    }
+  }
+
+  try {
+    // Run through pipeline -> cache handler -> retry handler -> fetch executor
+    const response = await pipeline.run(descriptor, async (currentDesc) => {
+      return handleCache(currentDesc, async (cacheDesc) => {
+        return retry(
+          () => execute(cacheDesc),
+          {
+            attempts: cacheDesc.retries,
+            signal: cacheDesc.signal
+          }
+        );
+      });
+    });
+
+    // Automatically extract response payload if successful
+    const contentType = response.headers.get('Content-Type') || '';
+    if (contentType.includes('application/json')) {
+      return response.json();
+    }
+    return response.text();
+  } finally {
+    // Perform guaranteed automatic cleanup of temporary request-specific listeners
+    for (const dispose of disposes) {
+      dispose();
+    }
+  }
+}
+
+export const api = {
+  get:    (url, opts) => request(url, 'GET', null, opts),
+  post:   (url, body, opts) => request(url, 'POST', body, opts),
+  put:    (url, body, opts) => request(url, 'PUT', body, opts),
+  patch:  (url, body, opts) => request(url, 'PATCH', body, opts),
+  delete: (url, opts) => request(url, 'DELETE', null, opts),
+  stream,
+  upload,
+  pipeline,
+  PlatformError,
+  
+  // Prefix registry singleton APIs
+  prefix: prefixes,
+
+  // Cache manager APIs
+  cache: apiCache,
+
+  // Event emitter hooks
+  on: (event, handler, signal) => events.on(event, handler, signal),
+  emit: (event, detail) => events.emit(event, detail)
+};
+
+export { pipeline, PlatformError, execute, retry, createNDJSONTransform, stream, upload, prefixes, events, apiCache as cache };
+
+

package/src/core/api/pipeline.js

@@ -0,0 +1,98 @@
+/**
+ * src/core/api/pipeline.js
+ *
+ * Composable interceptor chain.
+ * Manages request modification (outbound), short-circuiting (caching/mocking),
+ * and response normalization (inbound).
+ *
+ * Source: doc 11 — Networking §4, §5
+ */
+
+export class Pipeline {
+  #outbound = [];
+  #inbound = [];
+
+  /**
+   * Registers an outbound (request) interceptor.
+   * Outbound interceptors receive a request descriptor and can:
+   * 1. Return a modified descriptor to pass to the next interceptor.
+   * 2. Return a Response instance to short-circuit the pipeline (e.g. cache hit).
+   */
+  outbound(interceptor) {
+    if (typeof interceptor !== 'function') {
+      throw new Error('Pipeline interceptor must be a function');
+    }
+    this.#outbound.push(interceptor);
+    return this;
+  }
+
+  /**
+   * Registers an inbound (response/error) interceptor.
+   * Inbound interceptors receive the Response (or Error) and return a Response
+   * or throw a normalized Error.
+   */
+  inbound(interceptor) {
+    if (typeof interceptor !== 'function') {
+      throw new Error('Pipeline interceptor must be a function');
+    }
+    this.#inbound.push(interceptor);
+    return this;
+  }
+
+  /**
+   * Executes the pipeline with a given request descriptor and a final fetch executor.
+   */
+  async run(descriptor, executeFetch) {
+    let current = { ...descriptor };
+
+    // 1. Outbound Pipeline
+    for (const interceptor of this.#outbound) {
+      const result = await interceptor(current);
+      if (result instanceof Response) {
+        // Short circuit: Return mock or cached response
+        try {
+          result.requestId = current.requestId;
+        } catch (_) {}
+        return this.#runInbound(result);
+      }
+      if (result) {
+        current = result;
+      }
+    }
+
+    // 2. Fetch Execution
+    let response;
+    try {
+      response = await executeFetch(current);
+    } catch (err) {
+      // Pass network/timeout errors to the inbound pipeline for normalization
+      try {
+        err.requestId = current.requestId;
+      } catch (_) {}
+      return this.#runInbound(err);
+    }
+
+    // 3. Inbound Pipeline
+    try {
+      response.requestId = current.requestId;
+    } catch (_) {}
+    return this.#runInbound(response);
+  }
+
+  async #runInbound(responseOrError) {
+    let current = responseOrError;
+    for (const interceptor of this.#inbound) {
+      try {
+        current = await interceptor(current);
+      } catch (err) {
+        current = err;
+      }
+    }
+    if (current instanceof Error) {
+      throw current;
+    }
+    return current;
+  }
+}
+
+export const pipeline = new Pipeline();

package/src/core/api/plan.md

@@ -0,0 +1,209 @@
+# API Client & Cache Enhancement Plan
+
+This document outlines the blueprint for enhancing the `core.api` networking client with localized, fine-grained caching, prefix registration, namespace-level invalidation, and custom network/status-code events.
+
+---
+
+## 1. Architectural Architecture & Requirements
+
+We will extend `core.api` to provide:
+
+1. **Default Zero-Cache Policy:** All calls default to no cache, running directly against the network.
+2. **TTL/Expiry-based API Caching:** Active caching when `expiry` or `ttl` (Time-To-Live) options are provided. Hits cache first, falls back to the network on a miss, and caches successful responses.
+3. **Namespace-level Glob Invalidation:** Support for clearing the entire cache, a single URL, or a glob namespace pattern (e.g. `/user/*`).
+4. **Outbound Prefix Resolution:** Initializing base prefixes once (optionally) to cleanly rewrite and resolve endpoint URLs.
+5. **Network Event Hub:** An integrated event listener system firing on generic network failures (errors, timeouts) or specific responses (status codes like `401`, `500`, or content types like `json`, `text`).
+
+---
+
+## 2. Structural & Folder Layout
+
+In accordance with our naming and folder conventions (`RULE[user_global]`), we will group caching and events into highly structured subfolders under `src/core/api/`:
+
+```
+src/core/api/
+├── caches/               # Subfolder for caching adapters & glob matching
+│   ├── glob.js           # Glob/Namespace pattern matching helper
+│   └── index.js          # Unified local API cache client
+├── events/               # Subfolder for network telemetry events
+│   └── index.js          # API event emitter implementation
+├── prefixes/             # Subfolder for prefix/base URL resolving
+│   └── index.js          # Prefix store and path normalization
+├── index.js              # Core API client entry point
+├── fetch.js              # Network request executor
+├── pipeline.js           # Inbound/Outbound pipeline coordinator
+├── retry.js              # Exponential backoff retry handler
+├── stream.js             # Streams and NDJSON transform pipeline
+└── upload.js             # XMLHttpRequest-based upload gateway
+```
+
+---
+
+## 3. Technical Blueprint & Interface Design
+
+### Caches & Glob Purging (`src/core/api/caches/`)
+
+The API cache uses the native browser Cache API with custom header tags to track record creation times and TTL.
+
+```javascript
+// src/core/api/caches/index.js
+export class ApiCache {
+  constructor(name = 'platform-api-cache') {
+    this.name = name;
+  }
+
+  async get(url) {
+    if (typeof caches === 'undefined') return null;
+    const store = await caches.open(this.name);
+    const cached = await store.match(url);
+    if (!cached) return null;
+
+    const expiresAt = cached.headers.get('x-expires-at');
+    if (expiresAt && Date.now() > Number(expiresAt)) {
+      await store.delete(url);
+      return null;
+    }
+    return cached.clone();
+  }
+
+  async set(url, response, ttlMs) {
+    if (typeof caches === 'undefined') return;
+    const store = await caches.open(this.name);
+    const headers = new Headers(response.headers);
+    headers.set('x-expires-at', String(Date.now() + ttlMs));
+
+    const cloned = new Response(response.body ? response.clone().body : null, {
+      status: response.status,
+      statusText: response.statusText,
+      headers
+    });
+    await store.put(url, cloned);
+  }
+
+  async delete(pattern) {
+    if (typeof caches === 'undefined') return;
+    const store = await caches.open(this.name);
+
+    if (pattern.includes('*')) {
+      const regex = globToRegex(pattern);
+      const keys = await store.keys();
+      for (const req of keys) {
+        if (regex.test(req.url) || regex.test(new URL(req.url).pathname)) {
+          await store.delete(req);
+        }
+      }
+    } else {
+      await store.delete(pattern);
+    }
+  }
+
+  async clear() {
+    if (typeof caches === 'undefined') return;
+    await caches.delete(this.name);
+  }
+}
+```
+
+Glob to Regex conversion helper:
+
+```javascript
+// src/core/api/caches/glob.js
+export function globToRegex(pattern) {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  const wildcarded = escaped.replace(/\*/g, '.*');
+  return new RegExp(`^${wildcarded}$`);
+}
+```
+
+### Prefix Resolver (`src/core/api/prefixes/`)
+
+```javascript
+// src/core/api/prefixes/index.js
+export class PrefixRegistry {
+  #prefixes = new Map();
+
+  add(name, value) {
+    this.#prefixes.set(name, value);
+  }
+
+  resolve(url) {
+    if (url.startsWith('http://') || url.startsWith('https://')) {
+      return url;
+    }
+    for (const [prefix, base] of this.#prefixes.entries()) {
+      if (url.startsWith(`/${prefix}/`)) {
+        return base + url.slice(prefix.length + 1);
+      }
+      if (url.startsWith(`${prefix}/`)) {
+        return base + '/' + url.slice(prefix.length);
+      }
+    }
+    // Default fallback to registered root or baseline domain
+    const root = this.#prefixes.get('root') || this.#prefixes.get('default');
+    if (root) {
+      return root + (url.startsWith('/') ? url : '/' + url);
+    }
+    return url;
+  }
+}
+```
+
+### Telemetry Events (`src/core/api/events/`)
+
+```javascript
+// src/core/api/events/index.js
+export class ApiEventEmitter {
+  #listeners = new Map();
+
+  on(event, handler, signal) {
+    if (signal?.aborted) return () => {};
+    if (!this.#listeners.has(event)) {
+      this.#listeners.set(event, new Set());
+    }
+    const listener = { handler };
+    this.#listeners.get(event).add(listener);
+
+    const dispose = () => {
+      const set = this.#listeners.get(event);
+      if (set) {
+        set.delete(listener);
+        if (set.size === 0) this.#listeners.delete(event);
+      }
+    };
+
+    if (signal) {
+      signal.addEventListener('abort', dispose);
+    }
+    return dispose;
+  }
+
+  emit(event, detail) {
+    const set = this.#listeners.get(event);
+    if (!set) return;
+    const customEvent = { type: event, detail };
+    for (const listener of [...set]) {
+      try {
+        listener.handler(customEvent);
+      } catch (err) {
+        console.error(`Error in API event listener for "${event}":`, err);
+      }
+    }
+  }
+}
+```
+
+---
+
+## 4. Verification Plan
+
+### Automated Verification
+
+- Write comprehensive test coverage validating:
+  - Cache hits on active TTL/Expiry options.
+  - Glob namespace clearing matches (e.g. `/user/*` successfully purges `/user/profile` and `/user/settings`).
+  - Outbound path prefix expansion.
+  - Correct event dispatching for generic `'error'`, `'timeout'`, specific codes (`status:401`), and content types (`type:json`).
+
+### Integration Check
+
+- Assert network trace outputs and test page lifecycle triggers inside the browser environment.

package/src/core/api/prefixes/index.js

@@ -0,0 +1,66 @@
+/**
+ * src/core/api/prefixes/index.js
+ *
+ * Prefix and Base URL registry for relative path expansion.
+ * Allows clean routing/prefix matching at connection startup.
+ *
+ * Source: doc 11 — Networking §2, core/api/plan.md
+ */
+
+export class PrefixRegistry {
+  #prefixes = new Map();
+
+  /**
+   * Registers a new base URL prefix.
+   *
+   * @param {string} name
+   * @param {string} value
+   */
+  add(name, value) {
+    this.#prefixes.set(name, value);
+  }
+
+  /**
+   * Clears all registered prefixes.
+   */
+  clear() {
+    this.#prefixes.clear();
+  }
+
+  /**
+   * Resolves a URL prefix against registered base URLs.
+   *
+   * @param {string} url
+   * @returns {string}
+   */
+  resolve(url) {
+    if (url.startsWith('http://') || url.startsWith('https://') || url.startsWith('//')) {
+      return url;
+    }
+
+    for (const [prefix, base] of this.#prefixes.entries()) {
+      if (url.startsWith(`/${prefix}/`)) {
+        const suffix = url.slice(prefix.length + 2);
+        const normalizedBase = base.endsWith('/') ? base : base + '/';
+        return normalizedBase + suffix;
+      }
+      if (url.startsWith(`${prefix}/`)) {
+        const suffix = url.slice(prefix.length + 1);
+        const normalizedBase = base.endsWith('/') ? base : base + '/';
+        return normalizedBase + suffix;
+      }
+    }
+
+    // Default fallback base
+    const root = this.#prefixes.get('root') || this.#prefixes.get('default');
+    if (root) {
+      const normalizedRoot = root.endsWith('/') ? root.slice(0, -1) : root;
+      const normalizedUrl = url.startsWith('/') ? url : '/' + url;
+      return normalizedRoot + normalizedUrl;
+    }
+
+    return url;
+  }
+}
+
+export const prefixes = new PrefixRegistry();