webspresso 0.0.109 → 0.0.111

package/core/client/api.js

@@ -13,6 +13,8 @@
  * - Raw & streaming escape hatches (`api.raw`, `api.stream`)
  */
 
+const { isArray, isNumber } = require('./utils');
+
 const VALID_POLICIES = new Set(['latest', 'drop', 'queue', 'parallel']);
 const MUTATION_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
 const RESERVED_OPTION_KEYS = new Set([
@@ -27,17 +29,21 @@ const RESERVED_OPTION_KEYS = new Set([
   'csrfToken',
   'parseResponse',
   'onRefreshError',
+  'timeout',
+  'retry',
+  'retryMutations',
+  'raw',
 ]);
 
 /**
  * Structured Client Request Error
- * Distinguishes 'http', 'network', 'validation', and 'canceled' failure modes.
+ * Distinguishes 'http', 'network', 'validation', 'canceled', and 'timeout' failure modes.
  */
 class ClientRequestError extends Error {
   /**
    * @param {string} message
    * @param {object} details
-   * @param {'http'|'network'|'validation'|'canceled'} details.kind
+   * @param {'http'|'network'|'validation'|'canceled'|'timeout'} details.kind
    * @param {number|null} [details.status]
    * @param {string} [details.code]
    * @param {string} [details.method]
@@ -50,6 +56,7 @@ class ClientRequestError extends Error {
    * @param {unknown} [details.data]
    * @param {boolean} [details.isDropped]
    * @param {boolean} [details.isSuperseded]
+   * @param {boolean} [details.isTimedOut]
    * @param {Error} [details.cause]
    */
   constructor(message, details = {}) {
@@ -63,13 +70,18 @@ class ClientRequestError extends Error {
     this.key = details.key || '';
     this.fieldErrors = details.fieldErrors || {};
     this.fieldErrorList = details.fieldErrorList || {};
-    this.issues = Array.isArray(details.issues) ? details.issues : [];
+    this.issues = isArray(details.issues) ? details.issues : [];
     this.formError = details.formError || null;
     this.data = details.data !== undefined ? details.data : null;
     this.isCanceled = this.kind === 'canceled';
     this.isValidation = this.kind === 'validation';
     this.isNetwork = this.kind === 'network';
     this.isHttp = this.kind === 'http';
+    this.isTimedOut =
+      this.kind === 'timeout' ||
+      Boolean(details.isTimedOut) ||
+      this.code === 'REQUEST_TIMED_OUT' ||
+      this.status === 408;
     this.isDropped = Boolean(details.isDropped);
     this.isSuperseded = Boolean(details.isSuperseded);
     this.serverRollbackGuaranteed = false;
@@ -83,6 +95,7 @@ class ClientRequestError extends Error {
 }
 
 function defaultCodeForKind(kind, status) {
+  if (kind === 'timeout' || status === 408) return 'REQUEST_TIMED_OUT';
   if (kind === 'validation') return 'VALIDATION_ERROR';
   if (kind === 'canceled') return 'REQUEST_CANCELED';
   if (kind === 'network') return 'NETWORK_ERROR';
@@ -165,7 +178,7 @@ function buildRequestUrl(urlTemplate, params, query) {
   const searchParams = new URLSearchParams();
   for (const [key, rawVal] of Object.entries(query)) {
     if (rawVal === undefined) continue;
-    if (Array.isArray(rawVal)) {
+    if (isArray(rawVal)) {
       for (const item of rawVal) {
         if (item === undefined) continue;
         searchParams.append(key, item instanceof Date ? item.toISOString() : String(item));
@@ -194,7 +207,7 @@ function containsBinaryValue(value) {
   if (typeof Blob !== 'undefined' && value instanceof Blob) return true;
   if (typeof File !== 'undefined' && value instanceof File) return true;
   if (typeof FormData !== 'undefined' && value instanceof FormData) return true;
-  if (Array.isArray(value)) {
+  if (isArray(value)) {
     return value.some(containsBinaryValue);
   }
   for (const v of Object.values(value)) {
@@ -210,7 +223,7 @@ function objectToFormData(obj) {
   const fd = new FormData();
   for (const [key, val] of Object.entries(obj)) {
     if (val === undefined) continue;
-    if (Array.isArray(val)) {
+    if (isArray(val)) {
       for (const item of val) {
         if (item === undefined) continue;
         if (typeof Blob !== 'undefined' && item instanceof Blob) {
@@ -296,9 +309,9 @@ function extractValidationErrors(payload) {
 
   // 1. Direct fieldErrors map (e.g. { title: 'Required' } or { title: ['Required'] })
   const rawFieldErrors = errObj.fieldErrors || payload.fieldErrors || errObj.fields || null;
-  if (rawFieldErrors && typeof rawFieldErrors === 'object' && !Array.isArray(rawFieldErrors)) {
+  if (rawFieldErrors && typeof rawFieldErrors === 'object' && !isArray(rawFieldErrors)) {
     for (const [field, msgOrArr] of Object.entries(rawFieldErrors)) {
-      const list = Array.isArray(msgOrArr) ? msgOrArr.map(String) : [String(msgOrArr)];
+      const list = isArray(msgOrArr) ? msgOrArr.map(String) : [String(msgOrArr)];
       if (list.length > 0) {
         fieldErrors[field] = list[0];
         fieldErrorList[field] = list;
@@ -309,17 +322,17 @@ function extractValidationErrors(payload) {
 
   // 2. Zod / Webspresso `issues` or `details` array
   const rawIssues =
-    (Array.isArray(errObj.issues) && errObj.issues) ||
-    (Array.isArray(payload.issues) && payload.issues) ||
-    (Array.isArray(errObj.details) && errObj.details) ||
-    (Array.isArray(payload.details) && payload.details) ||
-    (Array.isArray(errObj.errors) && errObj.errors) ||
+    (isArray(errObj.issues) && errObj.issues) ||
+    (isArray(payload.issues) && payload.issues) ||
+    (isArray(errObj.details) && errObj.details) ||
+    (isArray(payload.details) && payload.details) ||
+    (isArray(errObj.errors) && errObj.errors) ||
     [];
 
   for (const issue of rawIssues) {
     if (!issue || typeof issue !== 'object') continue;
     let rawPath = '';
-    if (Array.isArray(issue.path)) {
+    if (isArray(issue.path)) {
       // Strip leading 'body' / 'query' / 'params' prefix from route validation paths
       const cleanParts =
         issue.path.length > 1 &&
@@ -382,8 +395,8 @@ function unwrapApiResultAndInvalidate(parsedBody, responseHeaders) {
   if (
     parsedBody &&
     typeof parsedBody === 'object' &&
-    !Array.isArray(parsedBody) &&
-    Array.isArray(parsedBody.invalidate) &&
+    !isArray(parsedBody) &&
+    isArray(parsedBody.invalidate) &&
     'data' in parsedBody
   ) {
     for (const tag of parsedBody.invalidate) {
@@ -431,9 +444,13 @@ function normalizeGetArgs(inputOrOptions, explicitOptions) {
     'query' in inputOrOptions ||
     'params' in inputOrOptions ||
     'policy' in inputOrOptions ||
+    'concurrency' in inputOrOptions ||
     'key' in inputOrOptions ||
     'signal' in inputOrOptions ||
-    'headers' in inputOrOptions;
+    'headers' in inputOrOptions ||
+    'timeout' in inputOrOptions ||
+    'retry' in inputOrOptions ||
+    'retryMutations' in inputOrOptions;
 
   if (hasExplicitWrapper && keys.every((k) => RESERVED_OPTION_KEYS.has(k))) {
     return { ...inputOrOptions };
@@ -456,6 +473,132 @@ function normalizeGetArgs(inputOrOptions, explicitOptions) {
   return opts;
 }
 
+/**
+ * Normalize retry options into an actionable execution descriptor.
+ * Never allows retries on mutations unless `retryMutations: true` is explicitly opted into.
+ *
+ * @param {boolean|number|object} [retryOpt]
+ * @param {string} upperMethod
+ * @param {boolean} [retryMutations=false]
+ * @returns {object|null}
+ */
+function normalizeRetryConfig(retryOpt, upperMethod, retryMutations = false) {
+  if (!retryOpt) return null;
+
+  // Strict invariant: never automatically retry mutation methods (POST, PUT, PATCH, DELETE)
+  if (MUTATION_METHODS.has(upperMethod) && !retryMutations) {
+    return null;
+  }
+
+  let count = 0;
+  let delay = 300;
+  let maxDelay = 5000;
+  let backoff = 'exponential';
+  let statusCodes = new Set([408, 429, 502, 503, 504]);
+  let onRetry = null;
+
+  if (isNumber(retryOpt)) {
+    count = Math.max(0, Math.floor(retryOpt));
+  } else if (retryOpt === true) {
+    count = 2;
+  } else if (typeof retryOpt === 'object' && retryOpt !== null) {
+    count = isNumber(retryOpt.count) ? Math.max(0, Math.floor(retryOpt.count)) : 2;
+    if (isNumber(retryOpt.delay)) delay = Math.max(0, retryOpt.delay);
+    if (isNumber(retryOpt.maxDelay)) maxDelay = Math.max(delay, retryOpt.maxDelay);
+    if (retryOpt.backoff === 'linear' || retryOpt.backoff === 'exponential') {
+      backoff = retryOpt.backoff;
+    }
+    if (isArray(retryOpt.statusCodes)) {
+      statusCodes = new Set(retryOpt.statusCodes);
+    }
+    if (typeof retryOpt.onRetry === 'function') {
+      onRetry = retryOpt.onRetry;
+    }
+  }
+
+  if (count <= 0) return null;
+
+  return {
+    count,
+    delay,
+    maxDelay,
+    backoff,
+    statusCodes,
+    onRetry,
+  };
+}
+
+/**
+ * Determine whether an error is transient and eligible for retry.
+ */
+function isRetryableError(err, statusCodes) {
+  if (!err) return false;
+  // Canceled, dropped, or superseded requests must never retry
+  if (err.isCanceled || err.isDropped || err.isSuperseded) return false;
+  // Network failures and timeouts are retryable
+  if (err.kind === 'network' || err.kind === 'timeout' || err.isTimedOut) return true;
+  // Transient HTTP status codes
+  if (isNumber(err.status) && statusCodes && statusCodes.has(err.status)) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Calculate retry delay with jitter.
+ */
+function calculateRetryDelay(attempt, config) {
+  const base = config.delay;
+  const max = config.maxDelay;
+  let calculated;
+  if (config.backoff === 'linear') {
+    calculated = base * attempt;
+  } else {
+    calculated = base * Math.pow(2, attempt - 1);
+  }
+  const jitter = Math.random() * 50;
+  return Math.min(max, calculated + jitter);
+}
+
+/**
+ * Abortable delay helper that rejects immediately if any signal aborts during wait.
+ */
+function abortableSleep(ms, signals = []) {
+  return new Promise((resolve, reject) => {
+    for (const sig of signals) {
+      if (sig && sig.aborted) {
+        return reject(new Error('Sleep aborted'));
+      }
+    }
+
+    let timer = null;
+    const cleanup = () => {
+      if (timer) clearTimeout(timer);
+      for (const sig of signals) {
+        if (sig && typeof sig.removeEventListener === 'function') {
+          sig.removeEventListener('abort', onAbort);
+        }
+      }
+    };
+
+    const onAbort = () => {
+      cleanup();
+      reject(new Error('Sleep aborted'));
+    };
+
+    for (const sig of signals) {
+      if (sig && typeof sig.addEventListener === 'function') {
+        sig.addEventListener('abort', onAbort, { once: true });
+      }
+    }
+
+    timer = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, ms);
+  });
+}
+
 /**
  * Create a Typed API Client instance.
  *
@@ -469,10 +612,19 @@ function normalizeGetArgs(inputOrOptions, explicitOptions) {
  * @param {() => boolean} [config.isConnected] - Controller connection check
  * @param {object} [config.debug] - Client debugger instance
  */
+function trimTrailingSlashes(str) {
+  if (!str) return '';
+  let end = str.length;
+  while (end > 0 && str.charCodeAt(end - 1) === 47) {
+    end--;
+  }
+  return end === str.length ? str : str.slice(0, end);
+}
+
 function createApiClient(config = {}) {
   const fetchImpl =
     config.fetch || (typeof globalThis.fetch === 'function' ? globalThis.fetch.bind(globalThis) : null);
-  const baseUrl = config.baseUrl ? String(config.baseUrl).replace(/\/+$/, '') : '';
+  const baseUrl = config.baseUrl ? trimTrailingSlashes(String(config.baseUrl)) : '';
   const lifecycleSignal = config.lifecycleSignal || null;
   const isConnected = typeof config.isConnected === 'function' ? config.isConnected : () => true;
   const debug = config.debug || null;
@@ -551,11 +703,83 @@ function createApiClient(config = {}) {
     }
 
     // Policy: 'queue' -> Chain onto existing queue for this key
+    const retryConfig = normalizeRetryConfig(
+      options.retry,
+      upperMethod,
+      Boolean(options.retryMutations)
+    );
+
+    async function executeWithRetry(runFn) {
+      if (!retryConfig) {
+        return runFn(requestId);
+      }
+
+      let attempt = 0;
+      while (true) {
+        attempt++;
+        const currentReqId = attempt === 1 ? requestId : `req_${++reqCounter}_${Date.now()}`;
+        try {
+          return await runFn(currentReqId);
+        } catch (err) {
+          const canRetry =
+            attempt <= retryConfig.count &&
+            isConnected() &&
+            (!lifecycleSignal || !lifecycleSignal.aborted) &&
+            (!options.signal || !options.signal.aborted) &&
+            isRetryableError(err, retryConfig.statusCodes);
+
+          if (!canRetry) {
+            throw err;
+          }
+
+          const delayMs = calculateRetryDelay(attempt, retryConfig);
+
+          if (typeof retryConfig.onRetry === 'function') {
+            try {
+              retryConfig.onRetry(err, attempt, delayMs);
+            } catch (_cbErr) {
+              // Ignore callback error
+            }
+          }
+
+          if (debug && typeof debug.trackRequestRetry === 'function') {
+            debug.trackRequestRetry({
+              requestId: currentReqId,
+              key: requestKey,
+              attempt,
+              delay: delayMs,
+              error: err,
+            });
+          }
+
+          const activeSignals = [options.signal, lifecycleSignal].filter(Boolean);
+          try {
+            await abortableSleep(delayMs, activeSignals);
+          } catch (_sleepErr) {
+            throw new ClientRequestError(
+              `Request canceled during retry backoff (${upperMethod} ${requestUrl}).`,
+              {
+                kind: 'canceled',
+                code: 'REQUEST_CANCELED',
+                method: upperMethod,
+                url: requestUrl,
+                key: requestKey,
+              }
+            );
+          }
+        }
+      }
+    }
+
     if (policy === 'queue') {
       const prevTail = queueMap.get(requestKey) || Promise.resolve();
       const nextTask = prevTail
         .catch(() => {})
-        .then(() => runSingleRequest(upperMethod, requestUrl, body, options, requestKey, requestId, 'queue'));
+        .then(() =>
+          executeWithRetry((subReqId) =>
+            runSingleRequest(upperMethod, requestUrl, body, options, requestKey, subReqId, 'queue')
+          )
+        );
       queueMap.set(
         requestKey,
         nextTask.catch(() => {})
@@ -563,14 +787,25 @@ function createApiClient(config = {}) {
       return nextTask;
     }
 
-    return runSingleRequest(upperMethod, requestUrl, body, options, requestKey, requestId, policy);
+    return executeWithRetry((subReqId) =>
+      runSingleRequest(upperMethod, requestUrl, body, options, requestKey, subReqId, policy)
+    );
   }
 
   async function runSingleRequest(upperMethod, requestUrl, body, options, requestKey, requestId, policy) {
     const abortController = new AbortController();
     let superseded = false;
+    let timedOut = false;
+    let timeoutTimer = null;
     let currentSeq = 1;
 
+    if (isNumber(options.timeout) && options.timeout > 0) {
+      timeoutTimer = setTimeout(() => {
+        timedOut = true;
+        abortController.abort();
+      }, options.timeout);
+    }
+
     // Policy: 'latest' -> Abort previous in-flight request for this key and increment sequence
     if (policy === 'latest') {
       const prev = latestMap.get(requestKey);
@@ -656,10 +891,34 @@ function createApiClient(config = {}) {
           signal: abortController.signal,
         });
       } catch (fetchErr) {
+        if (timeoutTimer) {
+          clearTimeout(timeoutTimer);
+          timeoutTimer = null;
+        }
         const latestEntry = policy === 'latest' ? latestMap.get(requestKey) : null;
         if (latestEntry && (latestEntry.seq !== currentSeq || latestEntry.superseded)) {
           superseded = true;
         }
+
+        if (timedOut) {
+          if (debug) {
+            debug.trackRequestEnd(requestId, { status: 'failed', errorKind: 'timeout' });
+          }
+          throw new ClientRequestError(
+            `Request timed out after ${options.timeout}ms (${upperMethod} ${requestUrl}).`,
+            {
+              kind: 'timeout',
+              status: 408,
+              code: 'REQUEST_TIMED_OUT',
+              method: upperMethod,
+              url: requestUrl,
+              key: requestKey,
+              isTimedOut: true,
+              cause: fetchErr,
+            }
+          );
+        }
+
         const isAbort =
           superseded ||
           abortController.signal.aborted ||
@@ -797,7 +1056,27 @@ function createApiClient(config = {}) {
       if (status === 204 || status === 205) {
         parsedBody = undefined;
       } else if (typeof response.text === 'function') {
-        const rawText = await response.text();
+        let rawText;
+        try {
+          rawText = await response.text();
+        } catch (bodyErr) {
+          if (timedOut) {
+            throw new ClientRequestError(
+              `Request timed out after ${options.timeout}ms (${upperMethod} ${requestUrl}).`,
+              {
+                kind: 'timeout',
+                status: 408,
+                code: 'REQUEST_TIMED_OUT',
+                method: upperMethod,
+                url: requestUrl,
+                key: requestKey,
+                isTimedOut: true,
+                cause: bodyErr,
+              }
+            );
+          }
+          throw bodyErr;
+        }
         checkSupersededOrDisconnected();
         if (!rawText || !rawText.trim()) {
           parsedBody = undefined;
@@ -811,7 +1090,26 @@ function createApiClient(config = {}) {
           parsedBody = rawText;
         }
       } else if (typeof response.json === 'function') {
-        parsedBody = await response.json();
+        try {
+          parsedBody = await response.json();
+        } catch (bodyErr) {
+          if (timedOut) {
+            throw new ClientRequestError(
+              `Request timed out after ${options.timeout}ms (${upperMethod} ${requestUrl}).`,
+              {
+                kind: 'timeout',
+                status: 408,
+                code: 'REQUEST_TIMED_OUT',
+                method: upperMethod,
+                url: requestUrl,
+                key: requestKey,
+                isTimedOut: true,
+                cause: bodyErr,
+              }
+            );
+          }
+          throw bodyErr;
+        }
         checkSupersededOrDisconnected();
       }
 
@@ -916,6 +1214,10 @@ function createApiClient(config = {}) {
 
       return data;
     } finally {
+      if (timeoutTimer) {
+        clearTimeout(timeoutTimer);
+        timeoutTimer = null;
+      }
       const set = inFlightMap.get(requestKey);
       if (set) {
         set.delete(requestId);
@@ -1029,5 +1331,9 @@ module.exports = {
   buildRequestUrl,
   extractValidationErrors,
   unwrapApiResultAndInvalidate,
+  normalizeRetryConfig,
+  isRetryableError,
+  calculateRetryDelay,
+  abortableSleep,
 };