zpy-tools/src/storage.js

提供了日期格式化、日期计算、文件格式化、本地缓存处理、Base64转File、File转Base64、节流防抖、数组排序、数据结构转化、深度比较两个对象是否包含相同的值等相关功能

/**
 * 设置 LocalStorage 项，并支持过期时间。
 * @param {string} key - 键名
 * @param {any} value - 键值
 * @param {number} [expiry] - 可选参数，过期时间（毫秒）
 */
function setLocalStorageItem(key, value, expiry) {
  try {
    // 参数验证
    if (typeof key !== "string" || key.trim() === "") {
      console.warn("Invalid key provided. Expected a non-empty string.");
      return;
    }

    if (value === undefined) {
      console.warn("Value is undefined. Nothing to store.");
      return;
    }

    let storageValue = value;

    // 如果提供了过期时间，则创建一个带有过期信息的对象
    if (expiry !== undefined && !isNaN(expiry)) {
      const now = Date.now();
      storageValue = {
        value: value,
        expiry: now + expiry,
      };
    }

    // 存储值：如果是字符串则直接存储；否则序列化为 JSON 字符串
    localStorage.setItem(
      key,
      typeof storageValue === "string"
        ? storageValue
        : JSON.stringify(storageValue)
    );
  } catch (error) {
    console.error("Error setting item in localStorage:", error);
  }
}

/**
 * 获取 LocalStorage 项，考虑过期时间。
 * @param {string} key - 键名
 * @returns {any | null} - 返回键对应的值或 null（如果已过期或不存在）
 */
function getLocalStorageItem(key) {
  try {
    // 确保 key 是一个非空字符串
    if (typeof key !== "string" || key.trim() === "") {
      console.warn("Invalid key provided. Expected a non-empty string.");
      return null;
    }

    const result = localStorage.getItem(key);
    if (!result) return null;

    let parsedResult;
    try {
      parsedResult = JSON.parse(result);
    } catch (e) {
      // 如果不是有效的 JSON，则认为它是一个普通字符串
      return result;
    }

    // 检查是否包含过期信息
    if (parsedResult && typeof parsedResult === "object") {
      if ("expiry" in parsedResult && parsedResult.expiry < Date.now()) {
        // 过期了，删除该项并返回 null
        localStorage.removeItem(key);
        return null;
      }
      return "value" in parsedResult ? parsedResult.value : parsedResult;
    }

    return parsedResult;
  } catch (error) {
    console.error("Error retrieving item from localStorage:", error);
    return null;
  }
}

/**
 * 清除 LocalStorage 项。
 * 如果提供了键名，则清除对应的单项；否则清除所有项。
 *
 * @param {string} [key] - 可选的键名，用于指定要清除的 LocalStorage 项。
 */
function clearLocalStorageItem(key) {
  try {
    // 如果 key 是 undefined 或 null，则清除所有项
    if (key == null) {
      console.warn(
        "No specific key provided. Clearing all items in localStorage."
      );
      localStorage.clear();
    } else if (typeof key !== "string") {
      console.warn("Invalid key type. Expected a string but received:", key);
    } else {
      console.log(`Cleared item with key: ${key}`);
      localStorage.removeItem(key);
    }
  } catch (error) {
    console.error("Error occurred while clearing localStorage item:", error);
  }
}

/**
 * 清除多个 LocalStorage 项。
 * @param {string[]} keys - 键名数组
 */
function clearLocalStorageItems(keys) {
  try {
    if (!Array.isArray(keys)) {
      console.warn("Expected an array of keys, but received:", keys);
      return;
    }

    keys.forEach((key) => {
      if (typeof key === "string") {
        localStorage.removeItem(key);
      } else {
        console.warn(`Skipping invalid key: ${key}. Keys must be strings.`);
      }
    });

    console.log(`${keys.length} item(s) cleared from localStorage.`);
  } catch (error) {
    console.error("Error occurred while clearing localStorage items:", error);
  }
}

module.exports = {
  setLocalStorageItem,
  getLocalStorageItem,
  clearLocalStorageItem,
  clearLocalStorageItems,
};