@anjianshi/utils 1.0.0

package/src/logging/adapt.ts

@@ -0,0 +1,40 @@
+import type { Debug } from 'debug'
+import { getLogger } from './index.js'
+
+/**
+ * 适配 debug package
+ */
+export function adaptDebugLib(debugLib: Debug, enable = '') {
+  // 不在 localStorage 里记录 debugLib enable 状态，
+  // 以解决 web worker 里读不到 localStorage 而无法启用 debugLib 日志的问题
+  const emulate = {
+    storage: {
+      data: {} as Record<string, string>,
+      getItem(name: string) {
+        return emulate.storage.data[name]
+      },
+      setItem(name: string, value: string) {
+        emulate.storage.data[name] = value
+      },
+      removeItem(name: string) {
+        delete emulate.storage.data[name]
+      },
+    },
+    save(namespaces: string) {
+      if (namespaces) emulate.storage.setItem('debug', namespaces)
+      else emulate.storage.removeItem('debug')
+    },
+    load() {
+      return emulate.storage.getItem('debug')
+    },
+  }
+  Object.assign(debugLib, emulate)
+
+  // 将 debugLib 日志转发给 logger
+  const logger = getLogger('3rd-library')
+  debugLib.log = logger.debug.bind(logger)
+
+  if (enable) {
+    debugLib.enable(enable)
+  }
+}

package/src/logging/formatters.ts

@@ -0,0 +1,23 @@
+/**
+ * 日志常用数据的格式化函数
+ */
+import { type LogInfo, LogLevel } from './index.js'
+
+const formatters = {
+  time(info: LogInfo) {
+    return info.time.format('HH:mm:ss.SSS')
+  },
+  datetime(info: LogInfo) {
+    return info.time.format('YY-MM-DD HH:mm:ss.SSS')
+  },
+  level(info: LogInfo) {
+    const map = {
+      [LogLevel.Debug]: 'debug',
+      [LogLevel.Info]: 'info',
+      [LogLevel.Warning]: 'warn',
+      [LogLevel.Error]: 'error',
+    }
+    return map[info.level]
+  },
+}
+export default formatters

package/src/logging/index.ts

@@ -0,0 +1,87 @@
+export { default as formatters } from './formatters.js'
+export * from './adapt.js'
+import dayjs, { type Dayjs } from 'dayjs'
+import { initDayJs } from '../init-dayjs.js'
+
+// 引入 logging 库会自动初始化 dayjs
+initDayJs()
+
+export enum LogLevel {
+  Debug = 1,
+  Info = 2,
+  Warning = 3,
+  Error = 4,
+}
+
+export interface LogInfo {
+  logger: string // logger name；有多级 logger 的情况下，这是最初的 logger 名称
+  level: LogLevel
+  time: Dayjs
+  args: unknown[] // log content
+}
+
+export class LogHandler {
+  log(info: LogInfo) {} // eslint-disable-line @typescript-eslint/no-unused-vars
+}
+
+export class Logger {
+  level = LogLevel.Info
+  handlers = new Set<LogHandler>()
+
+  constructor(
+    public name: string = '',
+    public base: Logger | null = null, // 指定上级 logger，当前 logger 记录的日志也会传递给上级
+  ) {}
+
+  setLevel(level: LogLevel) {
+    this.level = level
+  }
+
+  addHandler(handler: LogHandler) {
+    this.handlers.add(handler)
+  }
+
+  /**
+   * 创建一个以当前 logger 为 base 的 child logger
+   */
+  getChild(name: string) {
+    const fullname = this.name ? `${this.name}/${name}` : name
+    type Constructor = new (...args: ConstructorParameters<typeof Logger>) => Logger
+    // 这里加上 `as this` 才能让 TypeScript 判定，对继承了 Logger 的类调用此方法时，返回的是那个类而不是原始的 Logger 类的实例
+    return new (this.constructor as Constructor)(fullname, this) as this
+  }
+
+  log(level: LogLevel, args: unknown[]) {
+    this.logByInfo({ logger: this.name, level, time: dayjs(), args })
+  }
+  protected logByInfo(info: LogInfo) {
+    if (this.base) this.base.logByInfo(info)
+    if (this.level > info.level) return
+    for (const handler of this.handlers) {
+      handler.log(info)
+    }
+  }
+
+  debug(...args: any[]) {
+    this.log(LogLevel.Debug, args)
+  }
+  info(...args: any[]) {
+    this.log(LogLevel.Info, args)
+  }
+  warn(...args: any[]) {
+    this.log(LogLevel.Warning, args)
+  }
+  error(...args: any[]) {
+    this.log(LogLevel.Error, args)
+  }
+}
+
+/**
+ * 提供一套默认配置好的 logger
+ */
+const defaultLogger = new Logger()
+export { defaultLogger as logger }
+
+export function getLogger(name: string) {
+  return defaultLogger.getChild(name)
+}

package/src/url.ts

@@ -0,0 +1,153 @@
+/**
+ * URL 工具函数
+ * 部分灵感来自：https://www.npmjs.com/package/qs
+ *
+ * [名词定义]
+ * query: 指 a=1&b=2 格式的“查询字符串”或此类字符串的解析结果。
+ * search: URL 中的 search 部分，与 location.search 一致，空字符串或以 '?' 开头。
+ * hash: URL 中的 hash 部分，与 location.hash 一直，空字符串或以 '#' 开头。
+ */
+import isPlainObject from 'lodash/isPlainObject.js'
+
+/*
+将 URL 里的 query 内容解析成对象
+
+array:
+- 若开启，支持解析 a[]=1&a[]=2 格式的参数，会解析成一个数组 { a: ['1', '2'] }
+- 否则把 `a[]` 整体当做一个参数名 { 'a[]': '2' }
+
+strict:
+是否开启“严格模式”（默认不开启）。在非严格模式下，会做很多兼容处理：
+1. 支持直接传入 query string（a=1&b=2）；严格模式下，则需在开头补充一个 ?（?a=1&b=2）
+2. hash 里的内容也会被解析，以兼容拼接错误的 URL（把 query 拼到了 hash 后面）。
+3. 出现多个 ? 符号时，会把 ? 也当做 & 分隔符（index.html?a=1&b=2?c=3）
+
+小技巧：
+如果明确只想解析 hash 或 search 里的内容，可以传入 location.search / hash 而不是传入整个 location.href
+
+此函数不会对 query 值进行 decode，需自定处理
+*/
+function parseQuery(url: string, options?: { array?: false, strict?: boolean }): Record<string, string> // prettier-ignore
+function parseQuery(url: string, options: { array: true, strict?: boolean }): Record<string, string | string[]> // prettier-ignore
+function parseQuery(
+  url: string,
+  options?: { array?: boolean; strict?: boolean },
+): Record<string, string | string[]> {
+  if (!url) return {}
+  const { array = false, strict = false } = options ?? {}
+
+  const queryString = strict
+    ? (/^[^?#]*\?(.+?)(\?|#|$)/.exec(url) ?? ['', ''])[1] // 排除 hash、重复的 ? 符号
+    : url
+
+  const query: { [name: string]: string | string[] } = {}
+  const reg = /([^#?&]*)=([^#?&]*)/g
+  let re = reg.exec(queryString)
+  while (re) {
+    const [name, value] = [re[1]!, re[2]!]
+    if (name.endsWith('[]') && array) {
+      const realName = name.slice(0, -2)
+      if (Array.isArray(query[realName])) (query[realName] as string[]).push(value)
+      else query[realName] = [value]
+    } else {
+      query[name] = value
+    }
+    re = reg.exec(queryString)
+  }
+  return query
+}
+export { parseQuery }
+
+/*
+取 query 中指定参数的值
+- 参数存在，返回参数值（可能是空字符串）；不存在返回 null
+- 解析 query 固定基于 parseQuery() 的 { array: false, strict: false } 规则
+- 和 parseQuery() 一样，url 可以根据需要传 location.href/search/hash
+*/
+export function getQueryParam(name: string, url: string): string | null {
+  const query = parseQuery(url)
+  return typeof query[name] === 'string' ? query[name]! : null
+}
+
+/*
+把对象合并成 query string。
+支持字符串、数值、布尔值（不建议，考虑用 0 和 1 代替），数组会转换成 name[]=value 的格式
+*/
+type StringifyVal = string | number | boolean
+export function stringifyQuery(obj: { [key: string]: StringifyVal | StringifyVal[] | undefined }) {
+  if (!isPlainObject(obj)) return ''
+  return (
+    Object.entries(obj)
+      // 过滤值为 undefined 的项目，使其完全不出现在最终的 query 中
+      .filter((entry): entry is [string, StringifyVal | StringifyVal[]] => entry[1] !== undefined)
+      .map(([name, value]) => stringifyQueryItem(name, value))
+      .join('&')
+  )
+}
+function stringifyQueryItem(name: string, value: StringifyVal | StringifyVal[]): string {
+  if (Array.isArray(value))
+    return value.map(subValue => stringifyQueryItem(`${name}[]`, subValue)).join('&')
+  return `${name}=${value}`
+}
+
+/**
+ * 拆分 URL 的各个部分（search 不带 '?'，hash 不带 '#'）
+ */
+export function splitUrl(url: string): { base: string; search: string; hash: string } {
+  let hashIndex = url.indexOf('#')
+  if (hashIndex === -1) hashIndex = url.length
+
+  let searchIndex = url.slice(0, hashIndex).indexOf('?')
+  if (searchIndex === -1) searchIndex = hashIndex
+
+  return {
+    base: url.slice(0, searchIndex),
+    search: url.slice(searchIndex + 1, hashIndex),
+    hash: url.slice(hashIndex + 1),
+  }
+}
+
+/*
+把指定 search 和 hash 内容合并到 url 上
+
+search   object    与现有 search 合并，替换同名项（值为数组的，用新数组代替老的，不会合并数组）
+hash    string     不带 # 号；若 url 已有 hash，会用此值代替
+*/
+export function combineUrl(
+  origUrl: string,
+  search?: Record<string, string | string[]>,
+  hash?: string,
+) {
+  search = search ?? {}
+  hash = hash ?? ''
+
+  // 拆分原 url 的 search、hash
+  const { base, search: origSearch, hash: origHash } = splitUrl(origUrl)
+
+  // 拼接新 URL
+  let newUrl = base
+  const newSearch = stringifyQuery({ ...parseQuery(origSearch), ...search })
+  const newHash = hash || origHash
+  if (newSearch) newUrl += `?${newSearch}`
+  if (newHash) newUrl += `#${newHash}`
+  return newUrl
+}
+
+/*
+decodeURIComponent() 对于不规范编码的字符串可能会报错（例如字符串里出现了“%”）
+用此函数代替可避免此问题
+*/
+export function safeDecode(content: string) {
+  try {
+    return decodeURIComponent(content)
+  } catch (e) {
+    return content
+  }
+}
+
+/**
+ * 将 URL 中的 http:// 协议改成 https://
+ */
+export function ensureHttps(url: string | undefined) {
+  return url?.replace(/http:\/\//g, 'https://')
+}

package/url.d.ts

@@ -0,0 +1,28 @@
+declare function parseQuery(url: string, options?: {
+    array?: false;
+    strict?: boolean;
+}): Record<string, string>;
+declare function parseQuery(url: string, options: {
+    array: true;
+    strict?: boolean;
+}): Record<string, string | string[]>;
+export { parseQuery };
+export declare function getQueryParam(name: string, url: string): string | null;
+type StringifyVal = string | number | boolean;
+export declare function stringifyQuery(obj: {
+    [key: string]: StringifyVal | StringifyVal[] | undefined;
+}): string;
+/**
+ * 拆分 URL 的各个部分（search 不带 '?'，hash 不带 '#'）
+ */
+export declare function splitUrl(url: string): {
+    base: string;
+    search: string;
+    hash: string;
+};
+export declare function combineUrl(origUrl: string, search?: Record<string, string | string[]>, hash?: string): string;
+export declare function safeDecode(content: string): string;
+/**
+ * 将 URL 中的 http:// 协议改成 https://
+ */
+export declare function ensureHttps(url: string | undefined): string | undefined;

package/url.js

@@ -0,0 +1,116 @@
+/**
+ * URL 工具函数
+ * 部分灵感来自：https://www.npmjs.com/package/qs
+ *
+ * [名词定义]
+ * query: 指 a=1&b=2 格式的“查询字符串”或此类字符串的解析结果。
+ * search: URL 中的 search 部分，与 location.search 一致，空字符串或以 '?' 开头。
+ * hash: URL 中的 hash 部分，与 location.hash 一直，空字符串或以 '#' 开头。
+ */
+import isPlainObject from 'lodash/isPlainObject.js';
+function parseQuery(url, options) {
+    if (!url)
+        return {};
+    const { array = false, strict = false } = options ?? {};
+    const queryString = strict
+        ? (/^[^?#]*\?(.+?)(\?|#|$)/.exec(url) ?? ['', ''])[1] // 排除 hash、重复的 ? 符号
+        : url;
+    const query = {};
+    const reg = /([^#?&]*)=([^#?&]*)/g;
+    let re = reg.exec(queryString);
+    while (re) {
+        const [name, value] = [re[1], re[2]];
+        if (name.endsWith('[]') && array) {
+            const realName = name.slice(0, -2);
+            if (Array.isArray(query[realName]))
+                query[realName].push(value);
+            else
+                query[realName] = [value];
+        }
+        else {
+            query[name] = value;
+        }
+        re = reg.exec(queryString);
+    }
+    return query;
+}
+export { parseQuery };
+/*
+取 query 中指定参数的值
+- 参数存在，返回参数值（可能是空字符串）；不存在返回 null
+- 解析 query 固定基于 parseQuery() 的 { array: false, strict: false } 规则
+- 和 parseQuery() 一样，url 可以根据需要传 location.href/search/hash
+*/
+export function getQueryParam(name, url) {
+    const query = parseQuery(url);
+    return typeof query[name] === 'string' ? query[name] : null;
+}
+export function stringifyQuery(obj) {
+    if (!isPlainObject(obj))
+        return '';
+    return (Object.entries(obj)
+        // 过滤值为 undefined 的项目，使其完全不出现在最终的 query 中
+        .filter((entry) => entry[1] !== undefined)
+        .map(([name, value]) => stringifyQueryItem(name, value))
+        .join('&'));
+}
+function stringifyQueryItem(name, value) {
+    if (Array.isArray(value))
+        return value.map(subValue => stringifyQueryItem(`${name}[]`, subValue)).join('&');
+    return `${name}=${value}`;
+}
+/**
+ * 拆分 URL 的各个部分（search 不带 '?'，hash 不带 '#'）
+ */
+export function splitUrl(url) {
+    let hashIndex = url.indexOf('#');
+    if (hashIndex === -1)
+        hashIndex = url.length;
+    let searchIndex = url.slice(0, hashIndex).indexOf('?');
+    if (searchIndex === -1)
+        searchIndex = hashIndex;
+    return {
+        base: url.slice(0, searchIndex),
+        search: url.slice(searchIndex + 1, hashIndex),
+        hash: url.slice(hashIndex + 1),
+    };
+}
+/*
+把指定 search 和 hash 内容合并到 url 上
+
+search   object    与现有 search 合并，替换同名项（值为数组的，用新数组代替老的，不会合并数组）
+hash    string     不带 # 号；若 url 已有 hash，会用此值代替
+*/
+export function combineUrl(origUrl, search, hash) {
+    search = search ?? {};
+    hash = hash ?? '';
+    // 拆分原 url 的 search、hash
+    const { base, search: origSearch, hash: origHash } = splitUrl(origUrl);
+    // 拼接新 URL
+    let newUrl = base;
+    const newSearch = stringifyQuery({ ...parseQuery(origSearch), ...search });
+    const newHash = hash || origHash;
+    if (newSearch)
+        newUrl += `?${newSearch}`;
+    if (newHash)
+        newUrl += `#${newHash}`;
+    return newUrl;
+}
+/*
+decodeURIComponent() 对于不规范编码的字符串可能会报错（例如字符串里出现了“%”）
+用此函数代替可避免此问题
+*/
+export function safeDecode(content) {
+    try {
+        return decodeURIComponent(content);
+    }
+    catch (e) {
+        return content;
+    }
+}
+/**
+ * 将 URL 中的 http:// 协议改成 https://
+ */
+export function ensureHttps(url) {
+    return url?.replace(/http:\/\//g, 'https://');
+}