@hypen-space/core 0.2.11 → 0.3.0

package/src/retry.ts

@@ -0,0 +1,306 @@
+/**
+ * Retry Utility for Network Operations
+ *
+ * Provides configurable retry logic with exponential/linear backoff
+ * for handling transient failures in network operations.
+ */
+
+import { type Result, Ok, Err } from "./result.js";
+
+/**
+ * Options for retry behavior
+ */
+export interface RetryOptions {
+  /** Maximum number of attempts (default: 3) */
+  maxAttempts?: number;
+  /** Initial delay in milliseconds (default: 1000) */
+  delayMs?: number;
+  /** Backoff strategy (default: 'exponential') */
+  backoff?: "linear" | "exponential" | "none";
+  /** Maximum delay cap in milliseconds (default: 30000) */
+  maxDelayMs?: number;
+  /** Jitter factor 0-1 to randomize delays (default: 0.1) */
+  jitter?: number;
+  /** Callback on each retry attempt */
+  onRetry?: (attempt: number, error: Error, nextDelayMs: number) => void;
+  /** Optional predicate to determine if error is retryable */
+  shouldRetry?: (error: Error) => boolean;
+  /** AbortSignal for cancellation */
+  signal?: AbortSignal;
+}
+
+/**
+ * Default retry options
+ */
+const DEFAULT_OPTIONS: Required<Omit<RetryOptions, "onRetry" | "shouldRetry" | "signal">> = {
+  maxAttempts: 3,
+  delayMs: 1000,
+  backoff: "exponential",
+  maxDelayMs: 30000,
+  jitter: 0.1,
+};
+
+/**
+ * Calculate delay for a given attempt
+ */
+function calculateDelay(
+  attempt: number,
+  options: Required<Omit<RetryOptions, "onRetry" | "shouldRetry" | "signal">>
+): number {
+  let delay: number;
+
+  switch (options.backoff) {
+    case "exponential":
+      // 2^(attempt-1) * delayMs: 1x, 2x, 4x, 8x...
+      delay = options.delayMs * Math.pow(2, attempt - 1);
+      break;
+    case "linear":
+      // attempt * delayMs: 1x, 2x, 3x, 4x...
+      delay = options.delayMs * attempt;
+      break;
+    case "none":
+      delay = options.delayMs;
+      break;
+  }
+
+  // Apply jitter (randomize ±jitter%)
+  if (options.jitter > 0) {
+    const jitterRange = delay * options.jitter;
+    delay += (Math.random() * 2 - 1) * jitterRange;
+  }
+
+  // Cap at maxDelayMs
+  return Math.min(delay, options.maxDelayMs);
+}
+
+/**
+ * Sleep for a given duration, respecting abort signal
+ */
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new Error("Retry aborted"));
+      return;
+    }
+
+    const timeoutId = setTimeout(resolve, ms);
+
+    signal?.addEventListener("abort", () => {
+      clearTimeout(timeoutId);
+      reject(new Error("Retry aborted"));
+    });
+  });
+}
+
+/**
+ * Retry a function with configurable backoff
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const result = await retry(() => fetch('/api/data'));
+ *
+ * // With options
+ * const result = await retry(
+ *   () => fetch('/api/data'),
+ *   {
+ *     maxAttempts: 5,
+ *     delayMs: 2000,
+ *     backoff: 'exponential',
+ *     onRetry: (n, err) => console.log(`Attempt ${n} failed: ${err.message}`)
+ *   }
+ * );
+ * ```
+ */
+export async function retry<T>(
+  fn: () => T | Promise<T>,
+  options: RetryOptions = {}
+): Promise<T> {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  let lastError: Error = new Error("No attempts made");
+
+  for (let attempt = 1; attempt <= opts.maxAttempts; attempt++) {
+    try {
+      // Check for abort before each attempt
+      if (opts.signal?.aborted) {
+        throw new Error("Retry aborted");
+      }
+
+      return await fn();
+    } catch (e) {
+      lastError = e instanceof Error ? e : new Error(String(e));
+
+      // Check if we should retry this error
+      if (opts.shouldRetry && !opts.shouldRetry(lastError)) {
+        throw lastError;
+      }
+
+      // If this was the last attempt, don't wait
+      if (attempt === opts.maxAttempts) {
+        break;
+      }
+
+      // Calculate delay and notify
+      const delayMs = calculateDelay(attempt, opts);
+      opts.onRetry?.(attempt, lastError, delayMs);
+
+      // Wait before next attempt
+      await sleep(delayMs, opts.signal);
+    }
+  }
+
+  throw lastError;
+}
+
+/**
+ * Retry a function, returning a Result instead of throwing
+ *
+ * @example
+ * ```typescript
+ * const result = await retryResult(() => fetch('/api/data'));
+ * if (result.ok) {
+ *   console.log('Success:', result.value);
+ * } else {
+ *   console.error('All retries failed:', result.error);
+ * }
+ * ```
+ */
+export async function retryResult<T>(
+  fn: () => T | Promise<T>,
+  options: RetryOptions = {}
+): Promise<Result<T, Error>> {
+  try {
+    const value = await retry(fn, options);
+    return Ok(value);
+  } catch (e) {
+    return Err(e instanceof Error ? e : new Error(String(e)));
+  }
+}
+
+/**
+ * Create a retryable version of a function
+ *
+ * @example
+ * ```typescript
+ * const fetchWithRetry = withRetry(
+ *   (url: string) => fetch(url),
+ *   { maxAttempts: 3 }
+ * );
+ *
+ * const response = await fetchWithRetry('/api/data');
+ * ```
+ */
+export function withRetry<TArgs extends unknown[], TReturn>(
+  fn: (...args: TArgs) => TReturn | Promise<TReturn>,
+  options: RetryOptions = {}
+): (...args: TArgs) => Promise<TReturn> {
+  return (...args: TArgs) => retry(() => fn(...args), options);
+}
+
+/**
+ * Predefined retry conditions
+ */
+export const RetryConditions = {
+  /**
+   * Retry on network errors (fetch failures, timeouts)
+   */
+  networkErrors: (error: Error): boolean => {
+    const message = error.message.toLowerCase();
+    return (
+      message.includes("network") ||
+      message.includes("fetch") ||
+      message.includes("timeout") ||
+      message.includes("econnrefused") ||
+      message.includes("econnreset") ||
+      message.includes("socket")
+    );
+  },
+
+  /**
+   * Retry on specific HTTP status codes (from fetch Response)
+   */
+  httpRetryable: (error: Error & { status?: number }): boolean => {
+    const status = error.status;
+    if (!status) return false;
+    // Retry on 408, 429, 500, 502, 503, 504
+    return [408, 429, 500, 502, 503, 504].includes(status);
+  },
+
+  /**
+   * Retry on transient WebSocket errors
+   */
+  websocketErrors: (error: Error): boolean => {
+    const message = error.message.toLowerCase();
+    return (
+      message.includes("websocket") ||
+      message.includes("connection") ||
+      message.includes("close")
+    );
+  },
+
+  /**
+   * Combine multiple conditions (retry if any match)
+   */
+  any:
+    (...conditions: Array<(error: Error) => boolean>) =>
+    (error: Error): boolean =>
+      conditions.some((c) => c(error)),
+
+  /**
+   * Combine multiple conditions (retry if all match)
+   */
+  all:
+    (...conditions: Array<(error: Error) => boolean>) =>
+    (error: Error): boolean =>
+      conditions.every((c) => c(error)),
+};
+
+/**
+ * Preset configurations for common use cases
+ */
+export const RetryPresets = {
+  /**
+   * Aggressive retry for critical operations
+   */
+  aggressive: {
+    maxAttempts: 10,
+    delayMs: 500,
+    backoff: "exponential" as const,
+    maxDelayMs: 60000,
+    jitter: 0.2,
+  },
+
+  /**
+   * Conservative retry for non-critical operations
+   */
+  conservative: {
+    maxAttempts: 3,
+    delayMs: 2000,
+    backoff: "linear" as const,
+    maxDelayMs: 10000,
+    jitter: 0.1,
+  },
+
+  /**
+   * Fast retry for local operations (short delays)
+   */
+  fast: {
+    maxAttempts: 5,
+    delayMs: 100,
+    backoff: "exponential" as const,
+    maxDelayMs: 2000,
+    jitter: 0,
+  },
+
+  /**
+   * WebSocket reconnection preset
+   */
+  websocket: {
+    maxAttempts: 10,
+    delayMs: 1000,
+    backoff: "exponential" as const,
+    maxDelayMs: 30000,
+    jitter: 0.1,
+    shouldRetry: RetryConditions.websocketErrors,
+  },
+};

package/src/state.ts

@@ -1,7 +1,14 @@
 /**
  * State management with observer pattern and diffing
+ *
+ * Uses a proxy-based approach with self-detection to avoid
+ * creating nested proxies repeatedly.
  */
 
+// Symbol for proxy detection (more robust than string property)
+const IS_PROXY = Symbol.for('hypen.isProxy');
+const RAW_TARGET = Symbol.for('hypen.rawTarget');
+
 export type StatePath = string; // e.g., "user.name", "items.0.title"
 
 /**
@@ -21,7 +28,8 @@ export interface StateObserverOptions {
 }
 
 /**
- * Deep clone an object, handling circular references
+ * Deep clone an object, using structuredClone when available.
+ * Handles proxy objects, circular references, and special types.
  */
 function deepClone<T>(obj: T): T {
   // Handle primitives and null
@@ -29,56 +37,62 @@ function deepClone<T>(obj: T): T {
     return obj;
   }
 
+  // Handle functions (pass through, can't be cloned)
+  if (typeof obj === 'function') {
+    return obj;
+  }
+
+  // Handle proxy objects with snapshot method
+  if (typeof (obj as any).__getSnapshot === 'function') {
+    return (obj as any).__getSnapshot() as T;
+  }
+
+  // Handle types that can't be cloned (return as-is)
+  if (obj instanceof WeakMap || obj instanceof WeakSet) {
+    return obj;
+  }
+
   // Use a WeakMap to track visited objects and handle circular references
   const visited = new WeakMap();
 
   function cloneInternal(value: any): any {
-    // Handle primitives and null
     if (value === null || typeof value !== 'object') {
       return value;
     }
 
-    // Check if we've already cloned this object (circular reference)
-    if (visited.has(value)) {
-      return visited.get(value);
-    }
-
-    // Handle Date
-    if (value instanceof Date) {
-      return new Date(value.getTime());
+    // Functions can't be cloned, pass through
+    if (typeof value === 'function') {
+      return value;
     }
 
-    // Handle RegExp
-    if (value instanceof RegExp) {
-      return new RegExp(value.source, value.flags);
+    // Check for circular reference
+    if (visited.has(value)) {
+      return visited.get(value);
     }
 
-    // Handle Map
-    if (value instanceof Map) {
-      const mapClone = new Map();
-      visited.set(value, mapClone);
-      for (const [k, v] of value.entries()) {
-        mapClone.set(cloneInternal(k), cloneInternal(v));
-      }
-      return mapClone;
+    // Handle types that can't be cloned
+    if (value instanceof WeakMap || value instanceof WeakSet) {
+      return value;
     }
 
-    // Handle Set
-    if (value instanceof Set) {
-      const setClone = new Set();
-      visited.set(value, setClone);
-      for (const item of value.values()) {
-        setClone.add(cloneInternal(item));
+    // Try structuredClone for supported types (Date, Map, Set, etc.)
+    // This is faster than manual cloning for these types
+    if (
+      value instanceof Date ||
+      value instanceof RegExp ||
+      value instanceof Map ||
+      value instanceof Set ||
+      ArrayBuffer.isView(value) ||
+      value instanceof ArrayBuffer
+    ) {
+      try {
+        return structuredClone(value);
+      } catch {
+        // If structuredClone fails, fall through to manual handling
       }
-      return setClone;
-    }
-
-    // Handle WeakMap/WeakSet - cannot be cloned, return as-is
-    if (value instanceof WeakMap || value instanceof WeakSet) {
-      return value;
     }
 
-    // Handle Array
+    // Handle arrays
     if (Array.isArray(value)) {
       const arrClone: any[] = [];
       visited.set(value, arrClone);
@@ -94,12 +108,12 @@ function deepClone<T>(obj: T): T {
 
     // Clone string keys
     for (const key in value) {
-      if (value.hasOwnProperty(key)) {
+      if (Object.prototype.hasOwnProperty.call(value, key)) {
         objClone[key] = cloneInternal(value[key]);
       }
     }
 
-    // Clone Symbol keys (not enumerable by for...in)
+    // Clone Symbol keys
     const symbolKeys = Object.getOwnPropertySymbols(value);
     for (const sym of symbolKeys) {
       objClone[sym] = cloneInternal(value[sym]);
@@ -271,18 +285,23 @@ export function createObservableState<T extends object>(
     }
   }
 
-  // Cache proxies to handle circular references
-  const proxyCache = new WeakMap<any, any>();
+  // WeakMap to cache proxies by their raw target
+  // This is essential for circular reference handling
+  const proxyCache = new WeakMap<object, any>();
 
   function createProxy(target: any, basePath: string): any {
-    // Return cached proxy if it exists (handles circular references)
-    if (proxyCache.has(target)) {
-      return proxyCache.get(target);
-    }
+    // Check cache first (handles circular references)
+    const cached = proxyCache.get(target);
+    if (cached) return cached;
 
     const proxy = new Proxy(target, {
       get(obj, prop) {
-        const value = obj[prop];
+        // Self-detection: if checking IS_PROXY, return true
+        // This allows us to detect if a value is already proxied
+        if (prop === IS_PROXY) return true;
+
+        // Allow access to raw target (useful for debugging/serialization)
+        if (prop === RAW_TARGET) return obj;
 
         // Expose batch control methods
         if (prop === "__beginBatch") {
@@ -302,8 +321,16 @@ export function createObservableState<T extends object>(
           return () => deepClone(obj);
         }
 
+        const value = obj[prop];
+
         // Return proxied nested objects/arrays, but NOT special types
         if (value && typeof value === "object") {
+          // Fast path: if already a proxy, return as-is
+          // This check is O(1) and avoids WeakMap lookup
+          if ((value as any)[IS_PROXY]) {
+            return value;
+          }
+
           // Check for special object types that should not be proxied
           if (
             value instanceof Date ||
@@ -316,8 +343,15 @@ export function createObservableState<T extends object>(
             return value;
           }
 
-          // Proxy regular objects and arrays
-          return createProxy(value, basePath ? `${basePath}.${String(prop)}` : String(prop));
+          // Check cache for this value (handles circular refs and repeated access)
+          const cachedNested = proxyCache.get(value);
+          if (cachedNested) {
+            return cachedNested;
+          }
+
+          // Create proxy for nested object/array
+          const nestedProxy = createProxy(value, basePath ? `${basePath}.${String(prop)}` : String(prop));
+          return nestedProxy;
         }
 
         return value;
@@ -326,6 +360,12 @@ export function createObservableState<T extends object>(
       set(obj, prop, value) {
         const oldValue = obj[prop];
 
+        // If setting an object that's already a proxy, unwrap it first
+        // to store the raw value (prevents proxy-wrapping-proxy)
+        if (value && typeof value === "object" && (value as any)[IS_PROXY]) {
+          value = (value as any)[RAW_TARGET];
+        }
+
         // Set the new value
         obj[prop] = value;
 
@@ -381,3 +421,21 @@ export function getStateSnapshot<T>(state: T): T {
   }
   return deepClone(state);
 }
+
+/**
+ * Check if a value is a Hypen state proxy
+ */
+export function isStateProxy(value: unknown): boolean {
+  return value !== null && typeof value === 'object' && (value as any)[IS_PROXY] === true;
+}
+
+/**
+ * Get the raw (unwrapped) target from a proxy
+ * Returns the value as-is if not a proxy
+ */
+export function unwrapProxy<T>(value: T): T {
+  if (value !== null && typeof value === 'object' && (value as any)[IS_PROXY]) {
+    return (value as any)[RAW_TARGET];
+  }
+  return value;
+}

package/wasm-browser/README.md

@@ -1,5 +1,9 @@
 # Hypen Engine
 
+[![Rust](https://img.shields.io/badge/Rust-1.70+-orange?logo=rust)](https://www.rust-lang.org/)
+[![WASM](https://img.shields.io/badge/WASM-Ready-654FF0?logo=webassembly)](https://webassembly.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../LICENSE)
+
 The core reactive rendering engine for Hypen, written in Rust. Compiles to WASM for web/desktop or native binaries with UniFFI for mobile platforms.
 
 ## Quick Start

package/wasm-browser/package.json

@@ -5,7 +5,7 @@
     "Hypen Contributors"
   ],
   "description": "A Rust implementation of the Hypen engine",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/wasm-node/README.md

@@ -1,5 +1,9 @@
 # Hypen Engine
 
+[![Rust](https://img.shields.io/badge/Rust-1.70+-orange?logo=rust)](https://www.rust-lang.org/)
+[![WASM](https://img.shields.io/badge/WASM-Ready-654FF0?logo=webassembly)](https://webassembly.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../LICENSE)
+
 The core reactive rendering engine for Hypen, written in Rust. Compiles to WASM for web/desktop or native binaries with UniFFI for mobile platforms.
 
 ## Quick Start

package/wasm-node/package.json

@@ -4,7 +4,7 @@
     "Hypen Contributors"
   ],
   "description": "A Rust implementation of the Hypen engine",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "license": "MIT",
   "repository": {
     "type": "git",