@spoosh/core 0.12.0 → 0.13.0

package/dist/index.js

@@ -24,6 +24,7 @@ __export(src_exports, {
   Spoosh: () => Spoosh,
   __DEV__: () => __DEV__,
   buildUrl: () => buildUrl,
+  clone: () => clone,
   containsFile: () => containsFile,
   createClient: () => createClient,
   createEventEmitter: () => createEventEmitter,
@@ -35,6 +36,7 @@ __export(src_exports, {
   createProxyHandler: () => createProxyHandler,
   createSelectorProxy: () => createSelectorProxy,
   createStateManager: () => createStateManager,
+  createTracer: () => createTracer,
   executeFetch: () => executeFetch,
   extractMethodFromSelector: () => extractMethodFromSelector,
   extractPathFromSelector: () => extractPathFromSelector,
@@ -42,7 +44,9 @@ __export(src_exports, {
   form: () => form,
   generateTags: () => generateTags,
   getContentType: () => getContentType,
+  isAbortError: () => isAbortError,
   isJsonBody: () => isJsonBody,
+  isNetworkError: () => isNetworkError,
   isSpooshBody: () => isSpooshBody,
   json: () => json,
   mergeHeaders: () => mergeHeaders,
@@ -352,6 +356,60 @@ function resolvePath(path, params) {
   });
 }
 
+// src/utils/errors.ts
+var isNetworkError = (err) => err instanceof TypeError;
+var isAbortError = (err) => err instanceof DOMException && err.name === "AbortError";
+
+// src/utils/clone.ts
+function clone(value, seen = /* @__PURE__ */ new WeakMap()) {
+  if (value === void 0 || value === null || typeof value !== "object") {
+    return value;
+  }
+  if (seen.has(value)) {
+    return seen.get(value);
+  }
+  if (Array.isArray(value)) {
+    const arr = [];
+    seen.set(value, arr);
+    return value.map((v) => clone(v, seen));
+  }
+  if (value instanceof Date) {
+    return new Date(value.getTime());
+  }
+  if (value instanceof RegExp) {
+    return new RegExp(value.source, value.flags);
+  }
+  if (value.constructor !== Object) {
+    return value;
+  }
+  const obj = {};
+  seen.set(value, obj);
+  for (const key in value) {
+    if (Object.prototype.hasOwnProperty.call(value, key)) {
+      obj[key] = clone(value[key], seen);
+    }
+  }
+  return obj;
+}
+
+// src/utils/tracer.ts
+function createTracer(plugin, trace) {
+  const step = (stage, reason, options) => {
+    trace?.step(() => ({
+      plugin,
+      stage,
+      reason,
+      color: options?.color,
+      diff: options?.diff
+    }));
+  };
+  return {
+    return: (msg, options) => step("return", msg, options),
+    log: (msg, options) => step("log", msg, options),
+    skip: (msg, options) => step("skip", msg, options)
+  };
+}
+
 // src/transport/fetch.ts
 var fetchTransport = async (url, init) => {
   const res = await fetch(url, init);
@@ -434,9 +492,6 @@ var xhrTransport = (url, init, options) => {
 };
 
 // src/fetch.ts
-var delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-var isNetworkError = (err) => err instanceof TypeError;
-var isAbortError = (err) => err instanceof DOMException && err.name === "AbortError";
 async function executeFetch(baseUrl, path, method, defaultOptions, requestOptions, nextTags) {
   return executeCoreFetch({
     baseUrl,
@@ -486,9 +541,6 @@ async function executeCoreFetch(config) {
     ...fetchDefaults
   } = defaultOptions;
   const inputFields = buildInputFields(requestOptions);
-  const maxRetries = requestOptions?.retries ?? 3;
-  const baseDelay = requestOptions?.retryDelay ?? 1e3;
-  const retryCount = maxRetries === false ? 0 : maxRetries;
   const finalPath = path;
   const url = buildUrl(baseUrl, finalPath, requestOptions?.query);
   let headers = await mergeHeaders(defaultHeaders, requestOptions?.headers);
@@ -529,50 +581,44 @@ async function executeCoreFetch(config) {
   const resolvedTransport = resolveTransport(
     requestOptions?.transport ?? defaultTransport
   );
-  let lastError;
-  for (let attempt = 0; attempt <= retryCount; attempt++) {
-    try {
-      const result = await resolvedTransport(
-        url,
-        fetchInit,
-        requestOptions?.transportOptions
-      );
-      if (result.ok) {
-        return {
-          status: result.status,
-          data: result.data,
-          headers: result.headers,
-          error: void 0,
-          ...inputFields
-        };
-      }
+  if (requestOptions && headers) {
+    requestOptions.headers = headers;
+  }
+  try {
+    const result = await resolvedTransport(
+      url,
+      fetchInit,
+      requestOptions?.transportOptions
+    );
+    if (result.ok) {
       return {
         status: result.status,
-        error: result.data,
+        data: result.data,
         headers: result.headers,
+        error: void 0,
+        ...inputFields
+      };
+    }
+    const error = result.data !== void 0 && result.data !== "" ? result.data : {};
+    return {
+      status: result.status,
+      error,
+      headers: result.headers,
+      data: void 0,
+      ...inputFields
+    };
+  } catch (err) {
+    if (isAbortError(err)) {
+      return {
+        status: 0,
+        error: err,
         data: void 0,
+        aborted: true,
         ...inputFields
       };
-    } catch (err) {
-      if (isAbortError(err)) {
-        return {
-          status: 0,
-          error: err,
-          data: void 0,
-          aborted: true,
-          ...inputFields
-        };
-      }
-      lastError = err;
-      if (isNetworkError(err) && attempt < retryCount) {
-        const delayMs = baseDelay * Math.pow(2, attempt);
-        await delay(delayMs);
-        continue;
-      }
-      return { status: 0, error: lastError, data: void 0, ...inputFields };
     }
+    return { status: 0, error: err, data: void 0, ...inputFields };
   }
-  return { status: 0, error: lastError, data: void 0, ...inputFields };
 }
 
 // src/proxy/handler.ts
@@ -708,7 +754,7 @@ function createStateManager() {
         if (entry.tags) {
           existing.tags = entry.tags;
         }
-        if (entry.previousData !== void 0) {
+        if ("previousData" in entry) {
           existing.previousData = entry.previousData;
         }
         if (entry.stale !== void 0) {
@@ -865,47 +911,31 @@ function createEventEmitter() {
 
 // src/plugins/executor.ts
 function validateDependencies(plugins) {
-  const names = new Set(plugins.map((p) => p.name));
+  const pluginNames = new Set(plugins.map((p) => p.name));
   for (const plugin of plugins) {
-    for (const dep of plugin.dependencies ?? []) {
-      if (!names.has(dep)) {
-        throw new Error(
-          `Plugin "${plugin.name}" depends on "${dep}" which is not registered`
-        );
+    if (plugin.dependencies) {
+      for (const dep of plugin.dependencies) {
+        if (!pluginNames.has(dep)) {
+          throw new Error(
+            `Plugin "${plugin.name}" depends on "${dep}", but "${dep}" is not registered.`
+          );
+        }
       }
     }
   }
 }
-function sortByDependencies(plugins) {
-  const sorted = [];
-  const visited = /* @__PURE__ */ new Set();
-  const visiting = /* @__PURE__ */ new Set();
-  const pluginMap = new Map(plugins.map((p) => [p.name, p]));
-  function visit(plugin) {
-    if (visited.has(plugin.name)) return;
-    if (visiting.has(plugin.name)) {
-      throw new Error(
-        `Circular dependency detected involving "${plugin.name}"`
-      );
-    }
-    visiting.add(plugin.name);
-    for (const dep of plugin.dependencies ?? []) {
-      const depPlugin = pluginMap.get(dep);
-      if (depPlugin) visit(depPlugin);
-    }
-    visiting.delete(plugin.name);
-    visited.add(plugin.name);
-    sorted.push(plugin);
-  }
-  for (const plugin of plugins) {
-    visit(plugin);
-  }
-  return sorted;
+function sortByPriority(plugins) {
+  return [...plugins].sort((a, b) => {
+    const priorityA = a.priority ?? 0;
+    const priorityB = b.priority ?? 0;
+    return priorityA - priorityB;
+  });
 }
 function createPluginExecutor(initialPlugins = []) {
   validateDependencies(initialPlugins);
-  const plugins = sortByDependencies(initialPlugins);
+  const plugins = sortByPriority(initialPlugins);
   const frozenPlugins = Object.freeze([...plugins]);
+  const contextEnhancers = [];
   const createPluginAccessor = (context) => ({
     get(name) {
       const plugin = plugins.find((p) => p.name === name);
@@ -944,41 +974,47 @@ function createPluginExecutor(initialPlugins = []) {
         (p) => p.operations.includes(operationType)
       );
       const middlewares = applicablePlugins.filter((p) => p.middleware).map((p) => p.middleware);
+      const tracedCoreFetch = async () => {
+        const fetchTracer = context.tracer?.("spoosh:fetch");
+        fetchTracer?.log("Network request");
+        return coreFetch();
+      };
       let response;
       if (middlewares.length === 0) {
-        response = await coreFetch();
+        response = await tracedCoreFetch();
       } else {
         const chain = middlewares.reduceRight(
-          (next, middleware) => {
-            return () => middleware(
-              context,
-              next
-              // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            );
-          },
-          coreFetch
+          (next, middleware) => () => middleware(context, next),
+          tracedCoreFetch
         );
         response = await chain();
       }
       for (const plugin of applicablePlugins) {
         if (plugin.afterResponse) {
-          const newResponse = await plugin.afterResponse(
-            context,
-            response
-          );
+          const newResponse = await plugin.afterResponse(context, response);
           if (newResponse) {
             response = newResponse;
           }
         }
       }
+      context.eventEmitter.emit(
+        "spoosh:request-complete",
+        { context, queryKey: context.queryKey }
+      );
       return response;
     },
     getPlugins() {
       return frozenPlugins;
     },
+    registerContextEnhancer(enhancer) {
+      contextEnhancers.push(enhancer);
+    },
     createContext(input) {
       const ctx = input;
       ctx.plugins = createPluginAccessor(ctx);
+      for (const enhancer of contextEnhancers) {
+        enhancer(ctx);
+      }
       return ctx;
     }
   };
@@ -1007,15 +1043,15 @@ var Spoosh = class _Spoosh {
    * @example
    * ```ts
    * // Simple usage
-   * const client = new Spoosh<ApiSchema, Error>('/api');
+   * const spoosh = new Spoosh<ApiSchema, Error>('/api');
    *
    * // With default headers
-   * const client = new Spoosh<ApiSchema, Error>('/api', {
+   * const spoosh = new Spoosh<ApiSchema, Error>('/api', {
    *   headers: { 'X-API-Key': 'secret' }
    * });
    *
    * // With XHR transport (narrows available options to XHR-compatible fields)
-   * const client = new Spoosh<ApiSchema, Error>('/api', {
+   * const spoosh = new Spoosh<ApiSchema, Error>('/api', {
    *   transport: 'xhr',
    *   credentials: 'include',
    * });
@@ -1029,33 +1065,17 @@ var Spoosh = class _Spoosh {
   /**
    * Adds plugins to the Spoosh instance.
    *
-   * Returns a **new** Spoosh instance with updated plugin types (immutable pattern).
-   * Each call to `.use()` replaces the previous plugins rather than adding to them.
+   * Returns a configured Spoosh instance with the specified plugins.
+   * Can only be called once - the returned instance does not have `.use()`.
    *
    * @template TNewPlugins - The const tuple type of the new plugins array
    * @param plugins - Array of plugin instances to use
-   * @returns A new Spoosh instance with the specified plugins
-   *
-   * @example Single use() call
-   * ```ts
-   * const client = new Spoosh<Schema, Error>('/api')
-   *   .use([cachePlugin(), retryPlugin(), debouncePlugin()]);
-   * ```
-   *
-   * @example Chaining use() calls (replaces plugins)
-   * ```ts
-   * const client1 = new Spoosh<Schema, Error>('/api')
-   *   .use([cachePlugin()]);
+   * @returns A configured Spoosh instance (without `.use()` method)
    *
-   * // This replaces cachePlugin with retryPlugin
-   * const client2 = client1.use([retryPlugin()]);
-   * ```
-   *
-   * @example With plugin configuration
    * ```ts
-   * const client = new Spoosh<Schema, Error>('/api').use([
+   * const spoosh = new Spoosh<Schema, Error>('/api').use([
    *   cachePlugin({ staleTime: 5000 }),
-   *   retryPlugin({ retries: 3, retryDelay: 1000 }),
+   *   invalidationPlugin(),
    *   prefetchPlugin(),
    * ]);
    * ```
@@ -1112,7 +1132,7 @@ var Spoosh = class _Spoosh {
    *
    * @example
    * ```ts
-   * const client = new Spoosh<ApiSchema, Error>('/api').use([...]);
+   * const spoosh = new Spoosh<ApiSchema, Error>('/api').use([...]);
    * const { api } = client;
    *
    * // GET request
@@ -1542,7 +1562,7 @@ function createInfiniteReadController(options) {
       (key) => stateManager.subscribeCache(key, notify)
     );
   };
-  const createContext = (pageKey) => {
+  const createContext = (pageKey, requestOptions) => {
     return pluginExecutor.createContext({
       operationType: "infiniteRead",
       path,
@@ -1551,7 +1571,12 @@ function createInfiniteReadController(options) {
       tags,
       requestTimestamp: Date.now(),
       instanceId,
-      request: { headers: {} },
+      request: {
+        headers: {},
+        query: requestOptions?.query,
+        params: requestOptions?.params,
+        body: requestOptions?.body
+      },
       temp: /* @__PURE__ */ new Map(),
       pluginOptions,
       stateManager,
@@ -1575,7 +1600,7 @@ function createInfiniteReadController(options) {
     notify();
     abortController = new AbortController();
     const signal = abortController.signal;
-    const context = createContext(pageKey);
+    const context = createContext(pageKey, mergedRequest);
     const coreFetch = async () => {
       const fetchPromise = (async () => {
         try {
@@ -1730,7 +1755,7 @@ function createInfiniteReadController(options) {
       loadFromTracker();
       cachedState = computeState();
       subscribeToPages();
-      const context = createContext(trackerKey);
+      const context = createContext(trackerKey, initialRequest);
       pluginExecutor.executeLifecycle("onMount", "infiniteRead", context);
       refetchUnsubscribe = eventEmitter.on("refetch", (event) => {
         const isRelevant = event.queryKey === trackerKey || pageKeys.includes(event.queryKey);
@@ -1747,7 +1772,7 @@ function createInfiniteReadController(options) {
       }
     },
     unmount() {
-      const context = createContext(trackerKey);
+      const context = createContext(trackerKey, initialRequest);
       pluginExecutor.executeLifecycle("onUnmount", "infiniteRead", context);
       pageSubscriptions.forEach((unsub) => unsub());
       pageSubscriptions = [];
@@ -1755,7 +1780,7 @@ function createInfiniteReadController(options) {
       refetchUnsubscribe = null;
     },
     update(previousContext) {
-      const context = createContext(trackerKey);
+      const context = createContext(trackerKey, initialRequest);
       pluginExecutor.executeUpdateLifecycle(
         "infiniteRead",
         context,
@@ -1763,7 +1788,7 @@ function createInfiniteReadController(options) {
       );
     },
     getContext() {
-      return createContext(trackerKey);
+      return createContext(trackerKey, initialRequest);
     },
     setPluginOptions(opts) {
       pluginOptions = opts;