@qlover/fe-corekit 3.1.0 → 3.2.0

package/dist/index.cjs

@@ -51,15 +51,20 @@ __export(index_exports, {
   ResponsePlugin: () => ResponsePlugin,
   RetryPlugin: () => RetryPlugin,
   SimpleUrlBuilder: () => SimpleUrlBuilder,
-  SyncStorage: () => SyncStorage,
+  StorageExecutor: () => StorageExecutor,
   appendHeaders: () => appendHeaders,
   createAbortPromise: () => createAbortPromise,
+  createStoragePlugin: () => createStoragePlugin,
+  createStoragePluginWithStorage: () => createStoragePluginWithStorage,
   hasObjectKey: () => hasObjectKey,
   hasObjectKeyWithValue: () => hasObjectKeyWithValue,
   isAbortError: () => isAbortError,
   isAbsoluteUrl: () => isAbsoluteUrl,
   isAsString: () => isAsString,
+  isEncryptor: () => isEncryptor,
   isRequestAdapterResponse: () => isRequestAdapterResponse,
+  isSerializer: () => isSerializer,
+  isStorage: () => isStorage,
   normalizeHookNames: () => normalizeHookNames,
   raceWithAbort: () => raceWithAbort,
   runPluginHook: () => runPluginHook,
@@ -2881,6 +2886,9 @@ var RequestAdapterFetch = class {
     if (!baseURL) {
       return url;
     }
+    if (url.startsWith(baseURL)) {
+      return url;
+    }
     if (baseURL.endsWith("/") && url.startsWith("/")) {
       return baseURL.slice(0, -1) + url;
     }
@@ -3827,12 +3835,18 @@ var SimpleUrlBuilder = class {
             basePath = "/" + basePath;
           }
           let combinedPath = basePath;
-          if (!combinedPath.endsWith("/") && !url.startsWith("/")) {
-            combinedPath += "/";
+          if (!combinedPath.endsWith("/") || !url.startsWith("/")) {
+            if (!combinedPath.endsWith("/")) {
+              combinedPath += "/";
+            }
           }
           combinedPath += url.replace(/^\//, "");
           urlObject = new URL(combinedPath, "http://temp");
           shouldReturnPathOnly = true;
+        } else if (base && base === "api") {
+          const combinedPath = "/api/" + url.replace(/^\//, "");
+          urlObject = new URL(combinedPath, "http://temp");
+          shouldReturnPathOnly = true;
         } else if (base) {
           urlObject = new URL(url, "http://temp");
           shouldReturnPathOnly = true;
@@ -3981,6 +3995,7 @@ var SimpleUrlBuilder = class {
 };
 
 // src/request/impl/RequestPlugin.ts
+var import_lodash_es4 = require("lodash-es");
 var RequestPlugin = class {
   pluginName = "RequestPlugin";
   config;
@@ -4035,13 +4050,29 @@ var RequestPlugin = class {
    * @override
    */
   onBefore(ctx) {
-    const mergedConfig = this.mergeConfig(ctx.parameters);
+    ctx.setParameters(this.mergeConfig(ctx.parameters));
+  }
+  startsWith(url, baseUrl) {
+    return url.startsWith(baseUrl);
+  }
+  /**
+   * Main request handler
+   *
+   * This is the core of the plugin. It merges default plugin configuration with request context configuration,
+   * processes request data, builds the URL, and injects headers.
+   *
+   * @param config - Request configuration
+   * @returns Merged configuration with processed data, built URL, and injected headers
+   */
+  mergeConfig(config) {
+    const mergedConfig = this.createConfig(config);
     const processedData = this.processRequestData(mergedConfig);
     const builtUrl = this.buildUrl(mergedConfig);
+    if (builtUrl && mergedConfig.baseURL && this.startsWith(builtUrl, mergedConfig.baseURL)) {
+      delete mergedConfig.baseURL;
+    }
     const injectedHeaders = this.injectHeaders(mergedConfig);
-    ctx.setParameters({
-      ...ctx.parameters,
-      ...mergedConfig,
+    return Object.assign(mergedConfig, {
       data: processedData,
       url: builtUrl,
       headers: injectedHeaders
@@ -4059,8 +4090,8 @@ var RequestPlugin = class {
    * @param contextConfig - Configuration from request context
    * @returns Merged configuration
    */
-  mergeConfig(contextConfig) {
-    const merged = { ...this.config, ...contextConfig };
+  createConfig(contextConfig) {
+    const merged = Object.assign((0, import_lodash_es4.clone)(this.config), contextConfig);
     if (!("data" in contextConfig) && "data" in this.config) {
       merged.data = this.config.data;
     }
@@ -4074,13 +4105,10 @@ var RequestPlugin = class {
    * @throws {Error} If the built URL is empty or invalid
    */
   buildUrl(config) {
-    const url = this.urlBuilder.buildUrl(config);
-    if (!url || url.trim() === "") {
-      throw new Error(
-        `RequestPlugin: Invalid URL. URL cannot be empty. baseURL: ${config.baseURL ?? "undefined"}, url: ${config.url ?? "undefined"}`
-      );
+    if (config.allowEmptyUrl === false && !config.url && !config.baseURL) {
+      throw new Error("Empty URL is not allowed");
     }
-    return url;
+    return this.urlBuilder.buildUrl(config);
   }
   /**
    * Inject default headers into request configuration
@@ -4134,7 +4162,7 @@ var RequestPlugin = class {
 };
 
 // src/request/impl/ResponsePlugin.ts
-var import_lodash_es4 = require("lodash-es");
+var import_lodash_es5 = require("lodash-es");
 
 // src/request/utils/isRequestAdapterResponse.ts
 function isRequestAdapterResponse(value) {
@@ -4215,18 +4243,17 @@ var ResponsePlugin = class {
   async onSuccess(context) {
     const returnValue = context.returnValue;
     const config = context.parameters;
+    const result = await this.handleResponse(returnValue, config);
+    if (result) {
+      context.setReturnValue(result);
+    }
+  }
+  handleResponse(returnValue, config) {
     if (returnValue instanceof Response) {
-      const processedResponse = await this.processResponse(returnValue, config);
-      context.setReturnValue(processedResponse);
-      return;
+      return this.processResponse(returnValue, config);
     }
     if (isRequestAdapterResponse(returnValue)) {
-      const processedResponse = await this.processAdapterResponse(
-        returnValue,
-        config
-      );
-      context.setReturnValue(processedResponse);
-      return;
+      return this.processAdapterResponse(returnValue, config);
     }
   }
   /**
@@ -4298,7 +4325,7 @@ var ResponsePlugin = class {
    * ```
    */
   async parseResponseData(response, responseType) {
-    if ((0, import_lodash_es4.isFunction)(this.config.responseDataParser)) {
+    if ((0, import_lodash_es5.isFunction)(this.config.responseDataParser)) {
       return await this.config.responseDataParser(response, responseType);
     }
     return await this.defaultParseResponseData(response, responseType);
@@ -4322,7 +4349,7 @@ var ResponsePlugin = class {
     if (parser === false) {
       return response;
     }
-    if ((0, import_lodash_es4.isFunction)(parser)) {
+    if ((0, import_lodash_es5.isFunction)(parser)) {
       return await parser(response);
     }
     return await this.fallbackParseByContentType(response, normalizedType);
@@ -4340,13 +4367,13 @@ var ResponsePlugin = class {
     const lowerContentType = contentType.toLowerCase();
     if (lowerContentType.includes("application/json")) {
       const jsonParser = this.parsers.json;
-      if ((0, import_lodash_es4.isFunction)(jsonParser)) {
+      if ((0, import_lodash_es5.isFunction)(jsonParser)) {
         return jsonParser;
       }
     }
     if (lowerContentType.includes("text/") || lowerContentType.includes("application/xml") || lowerContentType.includes("application/xhtml")) {
       const textParser = this.parsers.text;
-      if ((0, import_lodash_es4.isFunction)(textParser)) {
+      if ((0, import_lodash_es5.isFunction)(textParser)) {
         return textParser;
       }
     }
@@ -4363,11 +4390,11 @@ var ResponsePlugin = class {
   getFallbackParsers() {
     const fallbackParsers = [];
     const jsonParser = this.parsers.json;
-    if ((0, import_lodash_es4.isFunction)(jsonParser)) {
+    if ((0, import_lodash_es5.isFunction)(jsonParser)) {
       fallbackParsers.push(jsonParser);
     }
     const textParser = this.parsers.text;
-    if ((0, import_lodash_es4.isFunction)(textParser)) {
+    if ((0, import_lodash_es5.isFunction)(textParser)) {
       fallbackParsers.push(textParser);
     }
     return fallbackParsers;
@@ -4904,71 +4931,45 @@ var Base64Serializer = class {
 
 // src/storage/impl/KeyStorage.ts
 var KeyStorage = class {
-  constructor(key, options = {}) {
+  constructor(key, storage) {
     this.key = key;
-    this.options = options;
-    try {
-      const localValue = options.storage?.getItem(key);
-      this.value = localValue ?? null;
-    } catch {
-      this.value = null;
-    }
+    this.storage = storage;
   }
   value;
-  mergeOptions(options) {
-    return {
-      ...this.options,
-      ...options
-    };
-  }
-  /**
-   * @override
-   */
-  getKey() {
-    return this.key;
-  }
-  /**
-   * @override
-   */
-  getValue() {
-    return this.value;
-  }
   /**
    * @override
    */
   get(options) {
-    const { storage, ...reset } = this.mergeOptions(options);
-    if (this.value != null) {
-      return this.value;
+    if (!this.storage) {
+      return this.value ?? null;
     }
-    if (storage) {
-      const val = storage.getItem(this.key, void 0, reset);
-      if (val == null) {
-        this.remove();
-        return null;
-      }
-      this.value = val;
-      return val;
+    const val = this.storage.getItem(this.key, options);
+    if (val == null) {
+      this.remove();
+      return null;
     }
-    return this.value;
+    this.value = val;
+    return val;
   }
   /**
    * @override
    */
-  set(token, options) {
-    const { storage, ...reset } = this.mergeOptions(options);
-    this.value = token;
-    if (storage) {
-      storage.setItem(this.key, token, reset);
+  set(value, options) {
+    if (!this.storage) {
+      this.value = value;
+      return;
     }
+    this.storage.setItem(this.key, value, options);
   }
   /**
    * @override
    */
   remove(options) {
-    const { storage, ...reset } = this.mergeOptions(options);
-    this.value = null;
-    storage?.removeItem(this.key, reset);
+    if (!this.storage) {
+      this.value = null;
+      return;
+    }
+    this.storage.removeItem(this.key, options);
   }
 };
 
@@ -5003,7 +5004,6 @@ var ObjectStorage = class {
   /**
    * Gets the number of items stored in the memory cache
    *
-   * @override
    * @returns The number of stored items in memory
    *
    * @example
@@ -5081,12 +5081,9 @@ var ObjectStorage = class {
     if (!storeValue) {
       return _dv;
     }
-    const value = this.serializer ? this.serializer.deserialize(storeValue, _dv) : storeValue;
+    const value = typeof storeValue === "string" && this.serializer ? this.serializer.deserialize(storeValue, _dv) : storeValue;
     return this.getRawValue(value, _dv);
   }
-  /**
-   * @override
-   */
   getRawValue(value, defaultValue) {
     if (this.isStorageValue(value)) {
       if (this.isExpired(value)) {
@@ -5180,268 +5177,146 @@ var ObjectStorage = class {
   isStorageValue(value) {
     return typeof value === "object" && value !== null && "key" in value && "value" in value;
   }
-  /**
-   * Gets the serializer instance
-   *
-   * Significance: Provides access to the serialization logic
-   * Core idea: Expose serializer for advanced use cases
-   * Main function: Return the serializer instance
-   * Main purpose: Enable direct access to serialization when needed
-   *
-   * @returns The serializer instance
-   *
-   * @example
-   * ```typescript
-   * const serializer = storage.getSerializer();
-   * if (serializer) {
-   *   // Direct access to serializer
-   * }
-   * ```
-   */
-  getSerializer() {
-    return this.serializer;
-  }
 };
 
-// src/storage/impl/SyncStorage.ts
-function toPipeValue(pipe) {
-  if ("type" in pipe && "pipe" in pipe) {
-    return pipe;
-  }
-  if ("serialize" in pipe && "deserialize" in pipe) {
-    return { pipe, type: "serialize" };
-  }
-  if ("encrypt" in pipe && "decrypt" in pipe) {
-    return { pipe, type: "encrypt" };
+// src/storage/utils/isStorage.ts
+var storageMethods = ["setItem", "getItem", "removeItem", "clear"];
+function isStorage(storage) {
+  if (storage == null || typeof storage !== "object") {
+    return false;
   }
-  if ("setItem" in pipe && "getItem" in pipe && "removeItem" in pipe && "clear" in pipe) {
-    return { pipe, type: "storage" };
+  for (const method of storageMethods) {
+    if (storage[method] == null || typeof storage[method] !== "function") {
+      return false;
+    }
   }
-  return null;
+  return true;
 }
-var operationMaps = {
-  setItem: {
-    serialize: (pipe, args) => pipe.serialize(...args),
-    encrypt: (pipe, args) => pipe.encrypt(...args),
-    storage: (pipe, args) => pipe.setItem(...args)
-  },
-  getItem: {
-    serialize: (pipe, args) => pipe.deserialize(...args),
-    encrypt: (pipe, args) => pipe.decrypt(...args),
-    storage: (pipe, args) => pipe.getItem(...args)
-  }
-};
-var SyncStorage = class {
-  /**
-   * Creates a new SyncStorage instance with pipeline support
-   *
-   * @param storage - Primary storage backend (e.g., localStorage, sessionStorage)
-   * @param pipes - Optional pipe or array of pipes for data transformation
-   *
-   * @example Single pipe
-   * ```typescript
-   * const storage = new SyncStorage(
-   *   localStorage,
-   *   new JSONSerializer()
-   * );
-   * ```
-   *
-   * @example Multiple pipes
-   * ```typescript
-   * const storage = new SyncStorage(
-   *   localStorage,
-   *   [
-   *     new JSONSerializer(),
-   *     new AESEncryptor('secret-key')
-   *   ]
-   * );
-   * ```
-   *
-   * @example No pipes (direct storage)
-   * ```typescript
-   * const storage = new SyncStorage(localStorage);
-   * // Data stored as-is without transformation
-   * ```
-   */
-  constructor(storage, pipes = []) {
-    this.storage = storage;
-    this.pipes = (Array.isArray(pipes) ? pipes : [pipes]).map((p) => toPipeValue(p)).filter((p) => p != null);
+
+// src/storage/utils/createStoragePlugin.ts
+function createStoragePluginWithStorage(storage) {
+  return {
+    get: storage.getItem.bind(storage),
+    set: storage.setItem.bind(storage),
+    remove: storage.removeItem.bind(storage),
+    clear: storage.clear.bind(storage),
+    type: "storage"
+  };
+}
+function isSerializer(plugin) {
+  return typeof plugin === "object" && plugin !== null && "serialize" in plugin && "deserialize" in plugin;
+}
+function isEncryptor(plugin) {
+  return typeof plugin === "object" && plugin !== null && "encrypt" in plugin && "decrypt" in plugin;
+}
+function createStoragePlugin(plugins) {
+  if (Array.isArray(plugins)) {
+    return plugins.map((plugin) => {
+      if (isSerializer(plugin)) {
+        return {
+          get: (_key, value) => plugin.deserialize(
+            value
+          ),
+          set: (_key, value) => plugin.serialize(value),
+          type: "serializer"
+        };
+      } else if (isEncryptor(plugin)) {
+        return {
+          get: (_key, value) => plugin.decrypt(
+            value
+          ),
+          set: (_key, value) => plugin.encrypt(value),
+          type: "encryptor"
+        };
+      } else if (isStorage(plugin)) {
+        return createStoragePluginWithStorage(plugin);
+      }
+      return plugin;
+    });
   }
+  return [createStoragePluginWithStorage(plugins)];
+}
+
+// src/storage/impl/StorageExecutor.ts
+var StorageExecutor = class {
+  plugins = [];
   /**
-   * Internal pipe value list with pre-determined types
-   *
-   * Stores the processed pipeline of transformations that will be
-   * applied to data during storage and retrieval operations.
-   *
-   * @protected
-   */
-  pipes;
-  /**
-   * Get the number of items in the primary storage
-   *
-   * Returns the count of items in the primary storage backend only.
-   * Does not include items in intermediate storage layers.
-   *
-   * @override
-   * @returns Number of items in primary storage
+   * Builds the plugin list from either a single `StorageInterface` or an array whose last element
+   * is the backing storage and preceding elements are transformers (e.g. serializer, encryptor).
    *
-   * @example
-   * ```typescript
-   * console.log(storage.length); // 5
-   * storage.setItem('newKey', 'value');
-   * console.log(storage.length); // 6
-   * ```
+   * @param plugins - Single storage instance or tuple of `[ ...transformers, storage ]`
    */
-  get length() {
-    return this.storage.length;
+  constructor(plugins) {
+    this.plugins = createStoragePlugin(plugins);
   }
   /**
-   * Store a value with pipeline processing
-   *
-   * Processes the value through the configured pipeline (serialization,
-   * encryption, intermediate storage) before storing in the primary storage.
-   *
-   * Pipeline execution:
-   * 1. Apply serialization (if configured)
-   * 2. Apply encryption (if configured)
-   * 3. Store in intermediate storage layers (if configured)
-   * 4. Store in primary storage
+   * Writes value through the plugin chain (forward). Each plugin may return a transformed value for the next.
    *
    * @override
-   * @template T - Type of value to store
-   * @param key - Storage key
-   * @param value - Value to store
-   * @param options - Optional storage options (e.g., expiration)
-   *
-   * @example Basic storage
-   * ```typescript
-   * storage.setItem('user', { id: 1, name: 'John' });
-   * ```
-   *
-   * @example With options
-   * ```typescript
-   * storage.setItem('session', { token: 'abc' }, { expire: 3600 });
-   * ```
    */
   setItem(key, value, options) {
-    let processedValue = value;
-    for (const currentPipe of this.pipes) {
-      const { type, pipe } = currentPipe;
-      if (type === "storage") {
-        pipe.setItem(
-          key,
-          processedValue,
-          options
-        );
-      } else {
-        const result = operationMaps.setItem[type](
-          // @ts-expect-error
-          pipe,
-          [processedValue]
-        );
-        if (result != null) {
-          processedValue = result;
-        }
+    let finalValue = value;
+    for (const plugin of this.plugins) {
+      const result = plugin.set(key, finalValue, options);
+      if (result !== void 0) {
+        finalValue = result;
       }
     }
-    this.storage.setItem(key, processedValue, options);
   }
   /**
-   * Retrieve a value with pipeline processing
+   * Reads value through the plugin chain in reverse order.
    *
-   * Retrieves the value from storage and processes it through the pipeline
-   * in reverse order (decryption, deserialization) to restore the original value.
+   * **Multiple storage plugins:** When the pipeline contains more than one storage plugin (e.g.
+   * `[sessionStorage, localStorage]`), getItem **only uses the value from the last storage** (the
+   * plugin at the end of the array). The iteration runs from tail to head; the first storage plugin
+   * encountered (which is the last in the array) is the only one whose `get` result is used. All
+   * other storage plugins are skipped and their values are ignored. This ensures a single, well-defined
+   * read source (e.g. prefer localStorage over sessionStorage when both are in the chain).
    *
-   * Retrieval strategy:
-   * 1. Try to retrieve from primary storage
-   * 2. If not found, try intermediate storage layers (in reverse order)
-   * 3. Apply decryption (if configured)
-   * 4. Apply deserialization (if configured)
-   * 5. Return processed value or default
+   * Pipe plugins (serializer, encryptor, etc.) are always applied to transform the value read from
+   * that single storage. If no value is found, returns `defaultValue` when provided, otherwise `null`.
    *
    * @override
-   * @template T - Type of value to retrieve
-   * @param key - Storage key
-   * @param defaultValue - Default value if key not found
-   * @param options - Optional retrieval options
-   * @returns Retrieved value or default, `null` if not found and no default
-   *
-   * @example Basic retrieval
-   * ```typescript
-   * const user = storage.getItem('user');
-   * if (user) {
-   *   console.log(user.name);
-   * }
-   * ```
-   *
-   * @example With default value
-   * ```typescript
-   * const config = storage.getItem('config', { theme: 'light' });
-   * console.log(config.theme); // 'light' if not found
-   * ```
    */
   getItem(key, defaultValue, options) {
-    let processedValue = this.storage.getItem(key, defaultValue, options);
-    if (processedValue == null) {
-      const reversedPipes2 = [...this.pipes].reverse();
-      for (const currentPipe of reversedPipes2) {
-        const { type, pipe } = currentPipe;
-        if (type !== "storage") {
-          continue;
-        }
-        const res = operationMaps.getItem[type](pipe, [
-          key,
-          processedValue,
-          options
-        ]);
-        if (res != null) {
-          processedValue = res;
-          break;
-        }
-      }
-    }
-    if (processedValue == null) {
-      return defaultValue ?? null;
-    }
-    const reversedPipes = [...this.pipes].reverse();
-    for (const currentPipe of reversedPipes) {
-      const { type, pipe } = currentPipe;
-      if (type === "storage") {
+    const lastIndex = this.plugins.length - 1;
+    let finalValue;
+    let storageHasValue = false;
+    for (let i = lastIndex; i >= 0; i--) {
+      const plugin = this.plugins[i];
+      const isStoragePlugin = plugin.type === "storage";
+      if (isStoragePlugin && storageHasValue) {
         continue;
       }
-      processedValue = operationMaps.getItem[type](
-        pipe,
-        [processedValue]
-      );
-    }
-    if (processedValue !== null && this.storage.getRawValue) {
-      processedValue = this.storage.getRawValue(processedValue, options);
+      const result = plugin.get(key, finalValue, options);
+      if (result !== void 0) {
+        finalValue = result;
+        if (isStoragePlugin) {
+          storageHasValue = true;
+        }
+      }
     }
-    return processedValue ?? null;
+    return finalValue ?? defaultValue ?? null;
   }
   /**
-   * Delete data items, delete from all storage layers
+   * Removes item for the given key from all plugins that implement `remove`.
    *
    * @override
-   * @param key - Storage key
-   * @param options - Delete options
    */
   removeItem(key, options) {
-    this.storage.removeItem(key, options);
-    this.pipes.filter((p) => p.type === "storage").forEach((p) => {
-      p.pipe.removeItem(key, options);
-    });
+    for (const plugin of this.plugins) {
+      plugin.remove?.(key, options);
+    }
   }
   /**
-     * Clear all data, including storage in the pipeline
-  
-     * @override
-        */
+   * Clears data in all plugins that implement `clear`.
+   *
+   * @override
+   */
   clear() {
-    this.storage.clear();
-    this.pipes.filter((p) => p.type === "storage").forEach((p) => {
-      p.pipe.clear();
-    });
+    for (const plugin of this.plugins) {
+      plugin.clear?.();
+    }
   }
 };
 // Annotate the CommonJS export names for ESM import in node:
@@ -5477,15 +5352,20 @@ var SyncStorage = class {
   ResponsePlugin,
   RetryPlugin,
   SimpleUrlBuilder,
-  SyncStorage,
+  StorageExecutor,
   appendHeaders,
   createAbortPromise,
+  createStoragePlugin,
+  createStoragePluginWithStorage,
   hasObjectKey,
   hasObjectKeyWithValue,
   isAbortError,
   isAbsoluteUrl,
   isAsString,
+  isEncryptor,
   isRequestAdapterResponse,
+  isSerializer,
+  isStorage,
   normalizeHookNames,
   raceWithAbort,
   runPluginHook,