@anjianshi/utils 1.0.9 → 1.2.0

package/.eslintrc.cjs

@@ -1,6 +1,6 @@
 /* eslint-env node */
 module.exports = {
   root: true,
-  extends: ['./node_modules/@anjianshi/presets/eslint-base.js'],
+  extends: ['./node_modules/@anjianshi/presets-eslint-base/index.js'],
   rules: {},
 }

package/env-browser/global.d.ts

@@ -1,5 +1,6 @@
 /**
  * 通过此模块注册全局变量以便于调试
+ * 变量会注册到 window.app = {} 下
  */
 declare global {
     interface Window {

package/env-browser/global.js

@@ -1,5 +1,6 @@
 /**
  * 通过此模块注册全局变量以便于调试
+ * 变量会注册到 window.app = {} 下
  */
 // web-worker 环境下不存在 window 变量，无法执行注册
 let hasWindow = false;

package/env-node/logging.d.ts

@@ -1,3 +1,4 @@
+import chalk from 'chalk';
 import { type Logger, type LogInfo, LogHandler } from '../logging/index.js';
 export * from '../logging/index.js';
 /**
@@ -24,14 +25,14 @@ export declare class ConsoleHandler extends LogHandler {
         };
     };
     static readonly levelColors: {
-        1: import("chalk").ChalkInstance;
-        2: import("chalk").ChalkInstance;
-        3: import("chalk").ChalkInstance;
-        4: import("chalk").ChalkInstance;
+        1: chalk.Chalk;
+        2: chalk.Chalk;
+        3: chalk.Chalk;
+        4: chalk.Chalk;
     };
     private static readonly loggerColors;
     private static readonly loggerColorMap;
-    static getLoggerColor(logger: string): "green" | "yellow" | "blue" | "cyan" | "magenta" | "greenBright" | "yellowBright" | "blueBright" | "cyanBright" | "magentaBright";
+    static getLoggerColor(logger: string): "green" | "yellow" | "blue" | "magenta" | "cyan" | "greenBright" | "yellowBright" | "blueBright" | "magentaBright" | "cyanBright";
 }
 /**
  * 写入文件日志
@@ -47,7 +48,7 @@ export declare class FileHandler extends LogHandler {
     readonly options: FileHandlerOptions;
     constructor(options?: Partial<FileHandlerOptions>);
     log(info: LogInfo): void;
-    protected formatDataItem(item: unknown): string;
+    protected stringifyDataItem(item: unknown): string;
     private buffer;
     private bufferSize;
     protected pushBuffer(...strings: string[]): void;

package/env-node/logging.js

@@ -7,7 +7,6 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import chalk from 'chalk';
 import dayjs from 'dayjs';
-import { removeANSIColor } from '../lang/index.js';
 import { logger as defaultLogger, LogLevel, LogHandler, formatters, } from '../logging/index.js';
 export * from '../logging/index.js';
 /**
@@ -21,9 +20,9 @@ export class ConsoleHandler extends LogHandler {
         const levelName = formatters.level(info);
         const loggerColor = chalk[ConsoleHandler.getLoggerColor(logger)];
         const prefix = [
-            chalk.white(`[${formatters.datetime(info)}]`),
+            chalk.white(`[${formatters.time(info)}]`),
             levelColor(`[${levelName}]`),
-            logger ? loggerColor(`[${logger}]`) : '',
+            loggerColor(`[${logger}]`),
         ].join('');
         method(prefix, ...args);
     }
@@ -88,7 +87,7 @@ export class FileHandler extends LogHandler {
         const itemStrings = [];
         let totalLength = prefix.length;
         for (const item of args) {
-            const itemString = this.formatDataItem(item);
+            const itemString = this.stringifyDataItem(item);
             // 截断过长的日志内容 Truncate overly long log messages
             if (totalLength + itemString.length < this.options.maxLength) {
                 itemStrings.push((totalLength === prefix.length ? '' : ' ') + itemString);
@@ -101,9 +100,9 @@ export class FileHandler extends LogHandler {
         }
         this.pushBuffer(prefix, ...itemStrings, '\n');
     }
-    formatDataItem(item) {
+    stringifyDataItem(item) {
         if (typeof item === 'string')
-            return removeANSIColor(item);
+            return item;
         if (item instanceof Error)
             return item.stack ?? String(item);
         try {

package/init-dayjs.js

@@ -1,8 +1,7 @@
-import dayjs from 'dayjs';
+import { extend, locale } from 'dayjs';
 import objectSupport from 'dayjs/plugin/objectSupport.js';
 import 'dayjs/locale/zh-cn.js';
 export function initDayJs() {
-    // dayjs 的类型标记错误，这两个方法只能通过 dayjs 对象访问，并不能直接引入
-    dayjs.extend(objectSupport);
-    dayjs.locale('zh-cn');
+    extend(objectSupport);
+    locale('zh-cn');
 }

package/lang/string.d.ts

@@ -16,15 +16,10 @@ export declare function safeParseInt(value: string | number, fallback?: number,
  */
 export declare function safeParseFloat(value: string | number, fallback: number): number;
 /**
- * Return file size for human reading.
- * From：https://stackoverflow.com/a/14919494
+ * 返回人类可读的文件尺寸
+ * 来自：https://stackoverflow.com/a/14919494
  *
- * si: true for radix of 1024；false for radix of 1000（default: false）
- * dp: how many decimal places to keep（保留几位小数）
+ * si: true 则使用 1000 进制，否则 1024 进制（默认 false）
+ * dp: 保留几位小数
  */
 export declare function readableSize(bytes: number, si?: boolean, dp?: number): string;
-/**
- * 移除字符串中的 ASNI Color 修饰符
- * https://stackoverflow.com/a/7150870/2815178
- */
-export declare function removeANSIColor(string: string): string;

package/lang/string.js

@@ -30,7 +30,6 @@ export function keywordCompare(keyword, target) {
  *
  * 以 0 开头是特例，例如 019 和 12 两个字符串，按直觉还是应该 019 在前面，毕竟本质还是字符串排序。
  *
- *
  * "123" "456"             数字排序
  * "123你好" "133我好"     字符串排序
  * "019" "12"              字符串排序
@@ -58,11 +57,11 @@ export function safeParseFloat(value, fallback) {
     return isFinite(raw) ? raw : fallback;
 }
 /**
- * Return file size for human reading.
- * From：https://stackoverflow.com/a/14919494
+ * 返回人类可读的文件尺寸
+ * 来自：https://stackoverflow.com/a/14919494
  *
- * si: true for radix of 1024；false for radix of 1000（default: false）
- * dp: how many decimal places to keep（保留几位小数）
+ * si: true 则使用 1000 进制，否则 1024 进制（默认 false）
+ * dp: 保留几位小数
  */
 export function readableSize(bytes, si = false, dp = 1) {
     const thresh = si ? 1000 : 1024;
@@ -79,12 +78,3 @@ export function readableSize(bytes, si = false, dp = 1) {
     } while (Math.round(Math.abs(bytes) * r) / r >= thresh && u < units.length - 1);
     return `${bytes.toFixed(dp)} ${units[u]}`;
 }
-/**
- * 移除字符串中的 ASNI Color 修饰符
- * https://stackoverflow.com/a/7150870/2815178
- */
-export function removeANSIColor(string) {
-    return string.replace(
-    // eslint-disable-next-line no-control-regex
-    /[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g, '');
-}

package/lang/types.d.ts

@@ -62,12 +62,13 @@ export interface Success<T = void> {
 export interface Failed<ET = string> {
     success: false;
     error: ET;
+    code?: number | string;
 }
 export type MaySuccess<T = void, ET = string> = Success<T> | Failed<ET>;
 declare function success(): Success;
 declare function success<T>(data: T): Success<T>;
 export { success };
-export declare function failed<ET>(error: ET): Failed<ET>;
+export declare function failed<ET>(error: ET, code?: number | string): Failed<ET>;
 /**
  * 若传入值为 success，格式化其 data；否则原样返回错误
  * 支持传入会返回 MaySuccess 的 Promise

package/lang/types.js

@@ -18,8 +18,8 @@ function success(data) {
     return { success: true, data };
 }
 export { success };
-export function failed(error) {
-    return { success: false, error };
+export function failed(error, code) {
+    return { success: false, error, code };
 }
 function formatSuccess(item, formatter) {
     if ('then' in item)

package/logging/adapt.d.ts

@@ -2,4 +2,4 @@ import type { Debug } from 'debug';
 /**
  * 适配 debug package
  */
-export declare function adaptDebugLib(debugLib: Debug, enable?: string, logger?: import("./index.js").Logger): void;
+export declare function adaptDebugLib(debugLib: Debug, enable?: string): void;

package/logging/adapt.js

@@ -2,7 +2,7 @@ import { getLogger } from './index.js';
 /**
  * 适配 debug package
  */
-export function adaptDebugLib(debugLib, enable = '', logger = getLogger('3rd-library')) {
+export function adaptDebugLib(debugLib, enable = '') {
     // 不在 localStorage 里记录 debugLib enable 状态，
     // 以解决 web worker 里读不到 localStorage 而无法启用 debugLib 日志的问题
     const emulate = {
@@ -30,12 +30,8 @@ export function adaptDebugLib(debugLib, enable = '', logger = getLogger('3rd-lib
     };
     Object.assign(debugLib, emulate);
     // 将 debugLib 日志转发给 logger
-    debugLib.log = (initial, ...rest) => {
-        // 移除开头的额外空格
-        if (typeof initial === 'string')
-            initial = initial.trimStart();
-        logger.debug(initial, ...rest);
-    };
+    const logger = getLogger('3rd-library');
+    debugLib.log = logger.debug.bind(logger);
     if (enable) {
         debugLib.enable(enable);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anjianshi/utils",
-  "version": "1.0.9",
+  "version": "1.2.0",
   "description": "Common JavaScript Utils",
   "homepage": "https://github.com/anjianshi/js-utils",
   "bugs": {
@@ -25,20 +25,19 @@
   },
   "main": "index.js",
   "dependencies": {
-    "chalk": "^5.3.0",
     "dayjs": "^1.11.10",
     "lodash": "^4.17.21"
   },
   "devDependencies": {
-    "@anjianshi/presets": "1.4.0",
+    "@anjianshi/presets-eslint-node": "^1.0.3",
+    "@anjianshi/presets-eslint-typescript": "^1.0.3",
+    "@anjianshi/presets-prettier": "^1.0.0",
+    "@anjianshi/presets-typescript": "^1.0.1",
     "@types/debug": "^4.1.9",
     "@types/lodash": "^4.14.199",
     "@types/node": "^20.8.6",
-    "eslint": "^8.51.0",
-    "prettier-not-stubborn": "^3.0.3",
-    "typescript": "^5.3.2",
     "vconsole": "^3.15.1"
   },
   "eslintIgnore": [],
-  "prettier": "@anjianshi/presets/prettierrc"
+  "prettier": "@anjianshi/presets-prettier/prettierrc"
 }

package/src/.eslintrc.cjs

@@ -1,8 +1,4 @@
 /* eslint-env node */
 module.exports = {
-  root: true,
-  extends: [
-    '../node_modules/@anjianshi/presets/eslint-base.js',
-    '../node_modules/@anjianshi/presets/eslint-typescript.js',
-  ],
+  extends: ['../node_modules/@anjianshi/presets-eslint-typescript/exclusive.js'],
 }

package/src/env-browser/global.ts

@@ -1,5 +1,6 @@
 /**
  * 通过此模块注册全局变量以便于调试
+ * 变量会注册到 window.app = {} 下
  */
 
 declare global {

package/src/env-node/.eslintrc.cjs

@@ -1,4 +1,4 @@
 /* eslint-env node */
 module.exports = {
-  extends: ['../../node_modules/@anjianshi/presets/eslint-node.js'],
+  extends: ['../../node_modules/@anjianshi/presets-eslint-node/exclusive.js'],
 }

package/src/env-node/logging.ts

@@ -7,7 +7,6 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import chalk from 'chalk'
 import dayjs from 'dayjs'
-import { removeANSIColor } from '../lang/index.js'
 import {
   logger as defaultLogger,
   type Logger,
@@ -30,9 +29,9 @@ export class ConsoleHandler extends LogHandler {
     const levelName = formatters.level(info)
     const loggerColor = chalk[ConsoleHandler.getLoggerColor(logger)]
     const prefix = [
-      chalk.white(`[${formatters.datetime(info)}]`),
+      chalk.white(`[${formatters.time(info)}]`),
       levelColor(`[${levelName}]`),
-      logger ? loggerColor(`[${logger}]`) : '',
+      loggerColor(`[${logger}]`),
     ].join('')
     method(prefix, ...args)
   }
@@ -121,7 +120,7 @@ export class FileHandler extends LogHandler {
     const itemStrings: string[] = []
     let totalLength = prefix.length
     for (const item of args) {
-      const itemString = this.formatDataItem(item)
+      const itemString = this.stringifyDataItem(item)
 
       // 截断过长的日志内容 Truncate overly long log messages
       if (totalLength + itemString.length < this.options.maxLength) {
@@ -138,8 +137,8 @@ export class FileHandler extends LogHandler {
     this.pushBuffer(prefix, ...itemStrings, '\n')
   }
 
-  protected formatDataItem(item: unknown) {
-    if (typeof item === 'string') return removeANSIColor(item)
+  protected stringifyDataItem(item: unknown) {
+    if (typeof item === 'string') return item
     if (item instanceof Error) return item.stack ?? String(item)
     try {
       const json = JSON.stringify(item) as string | undefined

package/src/init-dayjs.ts

@@ -1,9 +1,8 @@
-import dayjs from 'dayjs'
+import { extend, locale } from 'dayjs'
 import objectSupport from 'dayjs/plugin/objectSupport.js'
 import 'dayjs/locale/zh-cn.js'
 
 export function initDayJs() {
-  // dayjs 的类型标记错误，这两个方法只能通过 dayjs 对象访问，并不能直接引入
-  dayjs.extend(objectSupport)
-  dayjs.locale('zh-cn')
+  extend(objectSupport)
+  locale('zh-cn')
 }

package/src/lang/string.ts

@@ -32,7 +32,6 @@ export function keywordCompare(keyword: string, target: string) {
  *
  * 以 0 开头是特例，例如 019 和 12 两个字符串，按直觉还是应该 019 在前面，毕竟本质还是字符串排序。
  *
- *
  * "123" "456"             数字排序
  * "123你好" "133我好"     字符串排序
  * "019" "12"              字符串排序
@@ -62,11 +61,11 @@ export function safeParseFloat(value: string | number, fallback: number) {
 }
 
 /**
- * Return file size for human reading.
- * From：https://stackoverflow.com/a/14919494
+ * 返回人类可读的文件尺寸
+ * 来自：https://stackoverflow.com/a/14919494
  *
- * si: true for radix of 1024；false for radix of 1000（default: false）
- * dp: how many decimal places to keep（保留几位小数）
+ * si: true 则使用 1000 进制，否则 1024 进制（默认 false）
+ * dp: 保留几位小数
  */
 export function readableSize(bytes: number, si = false, dp = 1) {
   const thresh = si ? 1000 : 1024
@@ -82,15 +81,3 @@ export function readableSize(bytes: number, si = false, dp = 1) {
   } while (Math.round(Math.abs(bytes) * r) / r >= thresh && u < units.length - 1)
   return `${bytes.toFixed(dp)} ${units[u]!}`
 }
-
-/**
- * 移除字符串中的 ASNI Color 修饰符
- * https://stackoverflow.com/a/7150870/2815178
- */
-export function removeANSIColor(string: string) {
-  return string.replace(
-    // eslint-disable-next-line no-control-regex
-    /[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g,
-    '',
-  )
-}

package/src/lang/types.ts

@@ -73,6 +73,7 @@ export interface Success<T = void> {
 export interface Failed<ET = string> {
   success: false
   error: ET
+  code?: number | string
 }
 export type MaySuccess<T = void, ET = string> = Success<T> | Failed<ET>
 
@@ -83,25 +84,19 @@ function success<T = void>(data?: T) {
 }
 export { success }
 
-export function failed<ET>(error: ET): Failed<ET> {
-  return { success: false, error }
+export function failed<ET>(error: ET, code?: number | string): Failed<ET> {
+  return { success: false, error, code }
 }
 
 /**
  * 若传入值为 success，格式化其 data；否则原样返回错误
  * 支持传入会返回 MaySuccess 的 Promise
  */
-function formatSuccess<T, ET, FT>(
-  item: MaySuccess<T, ET>,
-  formatter: (data: T) => FT,
-): MaySuccess<FT, ET>
-function formatSuccess<T, ET, FT>(
-  item: Promise<MaySuccess<T, ET>>,
-  formatter: (data: T) => FT,
-): Promise<MaySuccess<FT, ET>>
+function formatSuccess<T, ET, FT>(item: MaySuccess<T, ET>, formatter: (data: T) => FT): MaySuccess<FT, ET> // prettier-ignore
+function formatSuccess<T, ET, FT>(item: Promise<MaySuccess<T, ET>>, formatter: (data: T) => FT): Promise<MaySuccess<FT, ET>> // prettier-ignore
 function formatSuccess<T, ET, FT>(
   item: MaySuccess<T, ET> | Promise<MaySuccess<T, ET>>,
-  formatter: (data: T) => FT,
+  formatter: (data: T) => FT
 ) {
   if ('then' in item) return item.then(finalItem => formatSuccess(finalItem, formatter))
   return item.success ? { ...item, data: formatter(item.data) } : item
@@ -113,10 +108,10 @@ export { formatSuccess }
  * 注意：空字符串和数字 0 也会判定为没有值
  */
 function truthy(
-  value: string | number | boolean | null | undefined,
+  value: string | number | boolean | null | undefined
 ): value is string | number | true
 function truthy<T>(
-  value: T | string | number | boolean | null | undefined,
+  value: T | string | number | boolean | null | undefined
 ): value is T | string | number | true
 function truthy<T>(value: T | string | number | boolean | null | undefined) {
   return value !== null && value !== undefined && value !== '' && value !== 0 && value !== false

package/src/logging/adapt.ts

@@ -4,7 +4,7 @@ import { getLogger } from './index.js'
 /**
  * 适配 debug package
  */
-export function adaptDebugLib(debugLib: Debug, enable = '', logger = getLogger('3rd-library')) {
+export function adaptDebugLib(debugLib: Debug, enable = '') {
   // 不在 localStorage 里记录 debugLib enable 状态，
   // 以解决 web worker 里读不到 localStorage 而无法启用 debugLib 日志的问题
   const emulate = {
@@ -31,11 +31,8 @@ export function adaptDebugLib(debugLib: Debug, enable = '', logger = getLogger('
   Object.assign(debugLib, emulate)
 
   // 将 debugLib 日志转发给 logger
-  debugLib.log = (initial?: unknown, ...rest: unknown[]) => {
-    // 移除开头的额外空格
-    if (typeof initial === 'string') initial = initial.trimStart()
-    logger.debug(initial, ...rest)
-  }
+  const logger = getLogger('3rd-library')
+  debugLib.log = logger.debug.bind(logger)
 
   if (enable) {
     debugLib.enable(enable)

package/src/logging/index.ts

@@ -14,7 +14,7 @@ export enum LogLevel {
 }
 
 export interface LogInfo {
-  logger: string // 生成此条日志的 logger 的 name；有多级 logger 的情况下，这是最初的 logger 名称
+  logger: string // logger name；有多级 logger 的情况下，这是最初的 logger 名称
   level: LogLevel
   time: Dayjs
   args: unknown[] // log content

package/src/url.ts

@@ -10,20 +10,21 @@
 import isPlainObject from 'lodash/isPlainObject.js'
 
 /*
-将 URL 里的 query 内容解析成对象
+从字符串中解析出 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
+在非严格模式下，如果明确只想解析 hash 或 search 里的内容，可以传入 location.search / hash 而不是传入整个 location.href
 
 此函数不会对 query 值进行 decode，需自定处理
 */
@@ -31,7 +32,7 @@ function parseQuery(url: string, options?: { array?: false, strict?: boolean }):
 function parseQuery(url: string, options: { array: true, strict?: boolean }): Record<string, string | string[]> // prettier-ignore
 function parseQuery(
   url: string,
-  options?: { array?: boolean; strict?: boolean },
+  options?: { array?: boolean; strict?: boolean }
 ): Record<string, string | string[]> {
   if (!url) return {}
   const { array = false, strict = false } = options ?? {}
@@ -58,21 +59,21 @@ function parseQuery(
 }
 export { parseQuery }
 
-/*
-取 query 中指定参数的值
-- 参数存在，返回参数值（可能是空字符串）；不存在返回 null
-- 解析 query 固定基于 parseQuery() 的 { array: false, strict: false } 规则
-- 和 parseQuery() 一样，url 可以根据需要传 location.href/search/hash
-*/
+/**
+ * 取 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 的格式
-*/
+/**
+ * 把对象合并成 query string。
+ * 支持字符串、数值、布尔值（不建议，考虑用 0 和 1 代替），数组会转换成 name[]=value 的格式
+ */
 type StringifyVal = string | number | boolean
 export function stringifyQuery(obj: { [key: string]: StringifyVal | StringifyVal[] | undefined }) {
   if (!isPlainObject(obj)) return ''
@@ -91,52 +92,56 @@ function stringifyQueryItem(name: string, value: StringifyVal | StringifyVal[]):
 }
 
 /**
- * 拆分 URL 的各个部分（search 不带 '?'，hash 不带 '#'）
+ * 拆分 URL 的各个部分
+ *
+ * bare 为 true，则 search 不带 '?'，hash 不带 '#'
+ * 否则和 location.search / hash 一样
  */
-export function splitUrl(url: string): { base: string; search: string; hash: string } {
+export function splitUrl(url: string, bare = true): { base: string; search: string; hash: string } {
   let hashIndex = url.indexOf('#')
   if (hashIndex === -1) hashIndex = url.length
+  const bareHash = url.slice(hashIndex + 1)
 
   let searchIndex = url.slice(0, hashIndex).indexOf('?')
   if (searchIndex === -1) searchIndex = hashIndex
+  const bareSearch = url.slice(searchIndex + 1, hashIndex)
 
   return {
     base: url.slice(0, searchIndex),
-    search: url.slice(searchIndex + 1, hashIndex),
-    hash: url.slice(hashIndex + 1),
+    search: bare ? bareSearch : bareSearch ? '?' + bareSearch : '',
+    hash: bare ? bareHash : bareHash ? '#' + bareHash : '',
   }
 }
 
-/*
-把指定 search 和 hash 内容合并到 url 上
-
-search   object    与现有 search 合并，替换同名项（值为数组的，用新数组代替老的，不会合并数组）
-hash    string     不带 # 号；若 url 已有 hash，会用此值代替
-*/
+/**
+ * 把指定 query 和 hash 内容合并到 url 上
+ *
+ * query   object    与现有 search 合并，替换同名项（值为数组的，用新数组代替老的，不会合并数组）
+ * hash    string    若 url 已有 hash，会用此值代替。带不带开头的 '?' 皆可。
+ */
 export function combineUrl(
   origUrl: string,
-  search?: Record<string, string | string[]>,
-  hash?: string,
+  query: Record<string, string | string[]> = {},
+  hash: string = ''
 ) {
-  search = search ?? {}
-  hash = hash ?? ''
+  if (hash.startsWith('#')) hash = hash.slice(1)
 
   // 拆分原 url 的 search、hash
   const { base, search: origSearch, hash: origHash } = splitUrl(origUrl)
 
   // 拼接新 URL
   let newUrl = base
-  const newSearch = stringifyQuery({ ...parseQuery(origSearch), ...search })
+  const newSearch = stringifyQuery({ ...parseQuery(origSearch), ...query })
   const newHash = hash || origHash
   if (newSearch) newUrl += `?${newSearch}`
   if (newHash) newUrl += `#${newHash}`
   return newUrl
 }
 
-/*
-decodeURIComponent() 对于不规范编码的字符串可能会报错（例如字符串里出现了“%”）
-用此函数代替可避免此问题
-*/
+/**
+ * decodeURIComponent() 对于不规范编码的字符串可能会报错（例如字符串里出现了“%”）
+ * 用此函数代替可避免此问题
+ */
 export function safeDecode(content: string) {
   try {
     return decodeURIComponent(content)

package/url.d.ts

@@ -7,20 +7,43 @@ declare function parseQuery(url: string, options: {
     strict?: boolean;
 }): Record<string, string | string[]>;
 export { parseQuery };
+/**
+ * 取 query 中指定参数的值
+ * - 参数存在，返回参数值（可能是空字符串）；不存在返回 null
+ * - 解析 query 固定基于 parseQuery() 的 { array: false, strict: false } 规则
+ * - 和 parseQuery() 一样，url 可以根据需要传 location.href/search/hash
+ */
 export declare function getQueryParam(name: string, url: string): string | null;
+/**
+ * 把对象合并成 query string。
+ * 支持字符串、数值、布尔值（不建议，考虑用 0 和 1 代替），数组会转换成 name[]=value 的格式
+ */
 type StringifyVal = string | number | boolean;
 export declare function stringifyQuery(obj: {
     [key: string]: StringifyVal | StringifyVal[] | undefined;
 }): string;
 /**
- * 拆分 URL 的各个部分（search 不带 '?'，hash 不带 '#'）
+ * 拆分 URL 的各个部分
+ *
+ * bare 为 true，则 search 不带 '?'，hash 不带 '#'
+ * 否则和 location.search / hash 一样
  */
-export declare function splitUrl(url: string): {
+export declare function splitUrl(url: string, bare?: boolean): {
     base: string;
     search: string;
     hash: string;
 };
-export declare function combineUrl(origUrl: string, search?: Record<string, string | string[]>, hash?: string): string;
+/**
+ * 把指定 query 和 hash 内容合并到 url 上
+ *
+ * query   object    与现有 search 合并，替换同名项（值为数组的，用新数组代替老的，不会合并数组）
+ * hash    string    若 url 已有 hash，会用此值代替。带不带开头的 '?' 皆可。
+ */
+export declare function combineUrl(origUrl: string, query?: Record<string, string | string[]>, hash?: string): string;
+/**
+ * decodeURIComponent() 对于不规范编码的字符串可能会报错（例如字符串里出现了“%”）
+ * 用此函数代替可避免此问题
+ */
 export declare function safeDecode(content: string): string;
 /**
  * 将 URL 中的 http:// 协议改成 https://

package/url.js

@@ -35,12 +35,12 @@ function parseQuery(url, options) {
     return query;
 }
 export { parseQuery };
-/*
-取 query 中指定参数的值
-- 参数存在，返回参数值（可能是空字符串）；不存在返回 null
-- 解析 query 固定基于 parseQuery() 的 { array: false, strict: false } 规则
-- 和 parseQuery() 一样，url 可以根据需要传 location.href/search/hash
-*/
+/**
+ * 取 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;
@@ -60,35 +60,40 @@ function stringifyQueryItem(name, value) {
     return `${name}=${value}`;
 }
 /**
- * 拆分 URL 的各个部分（search 不带 '?'，hash 不带 '#'）
+ * 拆分 URL 的各个部分
+ *
+ * bare 为 true，则 search 不带 '?'，hash 不带 '#'
+ * 否则和 location.search / hash 一样
  */
-export function splitUrl(url) {
+export function splitUrl(url, bare = true) {
     let hashIndex = url.indexOf('#');
     if (hashIndex === -1)
         hashIndex = url.length;
+    const bareHash = url.slice(hashIndex + 1);
     let searchIndex = url.slice(0, hashIndex).indexOf('?');
     if (searchIndex === -1)
         searchIndex = hashIndex;
+    const bareSearch = url.slice(searchIndex + 1, hashIndex);
     return {
         base: url.slice(0, searchIndex),
-        search: url.slice(searchIndex + 1, hashIndex),
-        hash: url.slice(hashIndex + 1),
+        search: bare ? bareSearch : bareSearch ? '?' + bareSearch : '',
+        hash: bare ? bareHash : bareHash ? '#' + bareHash : '',
     };
 }
-/*
-把指定 search 和 hash 内容合并到 url 上
-
-search   object    与现有 search 合并，替换同名项（值为数组的，用新数组代替老的，不会合并数组）
-hash    string     不带 # 号；若 url 已有 hash，会用此值代替
-*/
-export function combineUrl(origUrl, search, hash) {
-    search = search ?? {};
-    hash = hash ?? '';
+/**
+ * 把指定 query 和 hash 内容合并到 url 上
+ *
+ * query   object    与现有 search 合并，替换同名项（值为数组的，用新数组代替老的，不会合并数组）
+ * hash    string    若 url 已有 hash，会用此值代替。带不带开头的 '?' 皆可。
+ */
+export function combineUrl(origUrl, query = {}, hash = '') {
+    if (hash.startsWith('#'))
+        hash = hash.slice(1);
     // 拆分原 url 的 search、hash
     const { base, search: origSearch, hash: origHash } = splitUrl(origUrl);
     // 拼接新 URL
     let newUrl = base;
-    const newSearch = stringifyQuery({ ...parseQuery(origSearch), ...search });
+    const newSearch = stringifyQuery({ ...parseQuery(origSearch), ...query });
     const newHash = hash || origHash;
     if (newSearch)
         newUrl += `?${newSearch}`;
@@ -96,10 +101,10 @@ export function combineUrl(origUrl, search, hash) {
         newUrl += `#${newHash}`;
     return newUrl;
 }
-/*
-decodeURIComponent() 对于不规范编码的字符串可能会报错（例如字符串里出现了“%”）
-用此函数代替可避免此问题
-*/
+/**
+ * decodeURIComponent() 对于不规范编码的字符串可能会报错（例如字符串里出现了“%”）
+ * 用此函数代替可避免此问题
+ */
 export function safeDecode(content) {
     try {
         return decodeURIComponent(content);