@greypan/js-kit 1.0.0

package/dist/timer/controllable-interval.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @file timer
+ * @description 增强型定时器工具（ControllableInterval）
+ * 特性：
+ * 1.进度保留：暂停 (pause) 时记录剩余时间，恢复 (resume) 时补全当前周期，而非重新计时
+ * 2.状态可控：支持随时 start、pause、resume、stop
+ * 3.链路稳健：基于递归 setTimeout 实现，避免原生 setInterval 在回调耗时过长时的“堆积”效应
+ * 4.环境兼容：适配浏览器与 Node.js (SSR)，自动处理 Timeout 类型差异
+ * @example
+ * const timer = createControllableInterval(() => {
+ *   console.log('tick')
+ * }, 1000))
+ * timer.start()
+ * setTimeout(() => {
+ *   timer.pause() // 运行 800ms 后暂停，剩余 200ms
+ *   setTimeout(() => {
+ *     timer.resume() // 200ms 后立即触发回调，随后回归 1000ms 周期
+ *   }, 500)
+ * }, 800)
+ */
+export declare function defineControllableInterval(callback: () => void, interval: number): import('../plugin').Plugin<{
+    tick: (delay: number) => void;
+    start: () => void;
+    pause: () => void;
+    resume: () => void;
+    stop: () => void;
+}, object>;
+export declare function createControllableInterval(callback: () => void, interval: number): object & {
+    tick: (delay: number) => void;
+    start: () => void;
+    pause: () => void;
+    resume: () => void;
+    stop: () => void;
+};

package/dist/timer/controllable-interval.js

@@ -0,0 +1,41 @@
+import { definePlugin as e } from "../plugin/core.js";
+//#region src/timer/controllable-interval.ts
+function t(t, n) {
+	return e(() => {
+		let e = null, r = !1, i = 0, a = 0;
+		function o(i) {
+			a = Date.now(), e = setTimeout(() => {
+				t(), r || o(n);
+			}, i);
+		}
+		function s() {
+			e || r || o(n);
+		}
+		function c() {
+			if (r || !e) return;
+			r = !0, clearTimeout(e), e = null;
+			let t = Date.now() - a;
+			i = Math.max(0, n - t);
+		}
+		function l() {
+			r && (r = !1, o(i || n));
+		}
+		function u() {
+			e && clearTimeout(e), e = null, r = !1, i = 0;
+		}
+		return {
+			tick: o,
+			start: s,
+			pause: c,
+			resume: l,
+			stop: u
+		};
+	});
+}
+function n(e, n) {
+	return t(e, n).make();
+}
+//#endregion
+export { n as createControllableInterval, t as defineControllableInterval };
+
+//# sourceMappingURL=controllable-interval.js.map

package/dist/timer/controllable-interval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"controllable-interval.js","names":[],"sources":["../../src/timer/controllable-interval.ts"],"sourcesContent":["/**\n * @file timer\n * @description 增强型定时器工具（ControllableInterval）\n * 特性：\n * 1.进度保留：暂停 (pause) 时记录剩余时间，恢复 (resume) 时补全当前周期，而非重新计时\n * 2.状态可控：支持随时 start、pause、resume、stop\n * 3.链路稳健：基于递归 setTimeout 实现，避免原生 setInterval 在回调耗时过长时的“堆积”效应\n * 4.环境兼容：适配浏览器与 Node.js (SSR)，自动处理 Timeout 类型差异\n * @example\n * const timer = createControllableInterval(() => {\n *   console.log('tick')\n * }, 1000))\n * timer.start()\n * setTimeout(() => {\n *   timer.pause() // 运行 800ms 后暂停，剩余 200ms\n *   setTimeout(() => {\n *     timer.resume() // 200ms 后立即触发回调，随后回归 1000ms 周期\n *   }, 500)\n * }, 800)\n */\n\nimport { definePlugin } from '@/plugin'\n\nexport function defineControllableInterval(callback: () => void, interval: number) {\n  return definePlugin(() => {\n    let timerId: ReturnType<typeof setTimeout> | null = null\n    let isPaused = false\n    let remainingTime = 0\n    let lastStartTime = 0\n\n    function tick(delay: number) {\n      lastStartTime = Date.now()\n      timerId = setTimeout(() => {\n        callback()\n        // 只有在没被暂停的情况下，才继续下一次循环\n        if (!isPaused) tick(interval)\n      }, delay)\n    }\n\n    function start() {\n      if (timerId || isPaused) return\n\n      tick(interval)\n    }\n\n    function pause() {\n      if (isPaused || !timerId) return\n\n      isPaused = true\n      clearTimeout(timerId)\n      timerId = null\n\n      // 计算当前这一轮还剩多少时间没跑完\n      const diff = Date.now() - lastStartTime\n      remainingTime = Math.max(0, interval - diff)\n    }\n\n    function resume() {\n      if (!isPaused) return\n\n      isPaused = false\n      // 恢复执行：先跑完上一轮剩下的时间\n      tick(remainingTime || interval)\n    }\n\n    function stop() {\n      if (timerId) clearTimeout(timerId)\n\n      timerId = null\n      isPaused = false\n      remainingTime = 0\n    }\n\n    return {\n      tick,\n      start,\n      pause,\n      resume,\n      stop\n    }\n  })\n}\n\nexport function createControllableInterval(callback: () => void, interval: number) {\n  return defineControllableInterval(callback, interval).make()\n}\n"],"mappings":";;AAuBA,SAAgB,EAA2B,GAAsB,GAAkB;CACjF,OAAO,QAAmB;EACxB,IAAI,IAAgD,MAChD,IAAW,IACX,IAAgB,GAChB,IAAgB;EAEpB,SAAS,EAAK,GAAe;GAE3B,AADA,IAAgB,KAAK,IAAI,GACzB,IAAU,iBAAiB;IAGzB,AAFA,EAAS,GAEJ,KAAU,EAAK,CAAQ;GAC9B,GAAG,CAAK;EACV;EAEA,SAAS,IAAQ;GACX,KAAW,KAEf,EAAK,CAAQ;EACf;EAEA,SAAS,IAAQ;GACf,IAAI,KAAY,CAAC,GAAS;GAI1B,AAFA,IAAW,IACX,aAAa,CAAO,GACpB,IAAU;GAGV,IAAM,IAAO,KAAK,IAAI,IAAI;GAC1B,IAAgB,KAAK,IAAI,GAAG,IAAW,CAAI;EAC7C;EAEA,SAAS,IAAS;GACX,MAEL,IAAW,IAEX,EAAK,KAAiB,CAAQ;EAChC;EAEA,SAAS,IAAO;GAKd,AAJI,KAAS,aAAa,CAAO,GAEjC,IAAU,MACV,IAAW,IACX,IAAgB;EAClB;EAEA,OAAO;GACL;GACA;GACA;GACA;GACA;EACF;CACF,CAAC;AACH;AAEA,SAAgB,EAA2B,GAAsB,GAAkB;CACjF,OAAO,EAA2B,GAAU,CAAQ,CAAC,CAAC,KAAK;AAC7D"}

package/dist/timer/debounce.d.ts

@@ -0,0 +1,21 @@
+type StrictFunction = (...args: never) => unknown;
+type Debouncer<F extends StrictFunction, IsNullable extends boolean = true> = {
+    readonly call: (...args: Parameters<F>) => ReturnType<F> | (true extends IsNullable ? undefined : never);
+    readonly cancel: () => void;
+    readonly flush: () => ReturnType<F> | undefined;
+    readonly isPending: boolean;
+    readonly cachedValue: ReturnType<F> | undefined;
+};
+type DebounceOptions = {
+    readonly waitMs?: number;
+    readonly maxWaitMs?: number;
+};
+export declare function debounce<F extends StrictFunction>(func: F, options: DebounceOptions & {
+    readonly timing?: 'trailing';
+}): Debouncer<F>;
+export declare function debounce<F extends StrictFunction>(func: F, options: (DebounceOptions & {
+    readonly timing: 'both';
+}) | (Omit<DebounceOptions, 'maxWaitMs'> & {
+    readonly timing: 'leading';
+})): Debouncer<F, false>;
+export {};

package/dist/timer/debounce.js

@@ -0,0 +1,30 @@
+import { funnel as e } from "../node_modules/.pnpm/remeda@2.39.0/node_modules/remeda/dist/funnel.js";
+//#region src/timer/debounce.ts
+function t(t, { timing: n, waitMs: r, maxWaitMs: i }) {
+	if (i !== void 0 && r !== void 0 && i < r) throw Error(`debounce: maxWaitMs (${i.toString()}) cannot be less than waitMs (${r.toString()})`);
+	let a, o = e((e) => {
+		a = t(...e);
+	}, {
+		reducer: (e, ...t) => t,
+		minQuietPeriodMs: r ?? i ?? 0,
+		...i !== void 0 && { maxBurstDurationMs: i },
+		...n === "leading" ? { triggerAt: "start" } : n === "both" ? { triggerAt: "both" } : { triggerAt: "end" }
+	});
+	return {
+		call: (...e) => (o.call(...e), a),
+		flush: () => (o.flush(), a),
+		cancel: () => {
+			o.cancel();
+		},
+		get isPending() {
+			return !o.isIdle;
+		},
+		get cachedValue() {
+			return a;
+		}
+	};
+}
+//#endregion
+export { t as debounce };
+
+//# sourceMappingURL=debounce.js.map

package/dist/timer/debounce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debounce.js","names":[],"sources":["../../src/timer/debounce.ts"],"sourcesContent":["/**\n * @description remeda debounce 废弃了，这是 remeda 官方提供的替代封装\n * @link https://github.com/remeda/remeda/blob/main/packages/remeda/src/funnel.remeda-debounce.test.ts#L10\n */\nimport { funnel } from 'remeda'\n\ntype StrictFunction = (...args: never) => unknown\ntype Debouncer<F extends StrictFunction, IsNullable extends boolean = true> = {\n  readonly call: (...args: Parameters<F>) => ReturnType<F> | (true extends IsNullable ? undefined : never)\n  readonly cancel: () => void\n  readonly flush: () => ReturnType<F> | undefined\n  readonly isPending: boolean\n  readonly cachedValue: ReturnType<F> | undefined\n}\n\ntype DebounceOptions = {\n  readonly waitMs?: number\n  readonly maxWaitMs?: number\n}\n\nexport function debounce<F extends StrictFunction>(\n  func: F,\n  options: DebounceOptions & { readonly timing?: 'trailing' }\n): Debouncer<F>\nexport function debounce<F extends StrictFunction>(\n  func: F,\n  options:\n    | (DebounceOptions & { readonly timing: 'both' })\n    | (Omit<DebounceOptions, 'maxWaitMs'> & { readonly timing: 'leading' })\n): Debouncer<F, false /* call CAN'T return null */>\nexport function debounce<F extends StrictFunction>(\n  func: F,\n  {\n    timing,\n    waitMs,\n    maxWaitMs\n  }: DebounceOptions & {\n    readonly timing?: 'both' | 'leading' | 'trailing'\n  }\n) {\n  if (maxWaitMs !== undefined && waitMs !== undefined && maxWaitMs < waitMs) {\n    throw new Error(`debounce: maxWaitMs (${maxWaitMs.toString()}) cannot be less than waitMs (${waitMs.toString()})`)\n  }\n\n  let cachedValue: ReturnType<F> | undefined\n\n  const debouncingFunnel = funnel(\n    (args: Parameters<F>) => {\n      // Every time the function is invoked the cached value is updated.\n      // @ts-expect-error [ts2345, ts2322] -- TypeScript infers the generic sub-\n      // types too eagerly, making itself blind to the fact that the types\n      // match here.\n      cachedValue = func(...args)\n    },\n    {\n      // Debounce stores the latest args it was called with for the next\n      // invocation of the callback.\n      reducer: (_, ...args: Parameters<F>) => args,\n      minQuietPeriodMs: waitMs ?? maxWaitMs ?? 0,\n      ...(maxWaitMs !== undefined && { maxBurstDurationMs: maxWaitMs }),\n      ...(timing === 'leading'\n        ? { triggerAt: 'start' }\n        : timing === 'both'\n          ? { triggerAt: 'both' }\n          : { triggerAt: 'end' })\n    }\n  )\n\n  return {\n    call: (...args: Parameters<F>) => {\n      debouncingFunnel.call(...args)\n      return cachedValue\n    },\n\n    flush: () => {\n      debouncingFunnel.flush()\n      return cachedValue\n    },\n\n    cancel: () => {\n      debouncingFunnel.cancel()\n    },\n\n    get isPending() {\n      return !debouncingFunnel.isIdle\n    },\n\n    get cachedValue() {\n      return cachedValue\n    }\n  }\n}\n"],"mappings":";;AA8BA,SAAgB,EACd,GACA,EACE,WACA,WACA,gBAIF;CACA,IAAI,MAAc,KAAA,KAAa,MAAW,KAAA,KAAa,IAAY,GACjE,MAAU,MAAM,wBAAwB,EAAU,SAAS,EAAE,gCAAgC,EAAO,SAAS,EAAE,EAAE;CAGnH,IAAI,GAEE,IAAmB,GACtB,MAAwB;EAKvB,IAAc,EAAK,GAAG,CAAI;CAC5B,GACA;EAGE,UAAU,GAAG,GAAG,MAAwB;EACxC,kBAAkB,KAAU,KAAa;EACzC,GAAI,MAAc,KAAA,KAAa,EAAE,oBAAoB,EAAU;EAC/D,GAAI,MAAW,YACX,EAAE,WAAW,QAAQ,IACrB,MAAW,SACT,EAAE,WAAW,OAAO,IACpB,EAAE,WAAW,MAAM;CAC3B,CACF;CAEA,OAAO;EACL,OAAO,GAAG,OACR,EAAiB,KAAK,GAAG,CAAI,GACtB;EAGT,cACE,EAAiB,MAAM,GAChB;EAGT,cAAc;GACZ,EAAiB,OAAO;EAC1B;EAEA,IAAI,YAAY;GACd,OAAO,CAAC,EAAiB;EAC3B;EAEA,IAAI,cAAc;GAChB,OAAO;EACT;CACF;AACF"}

package/dist/timer/index.d.ts

@@ -0,0 +1,2 @@
+export * from './controllable-interval';
+export * from './debounce';

package/dist/url/index.d.ts

@@ -0,0 +1,9 @@
+type QueryValue = string | number | boolean | undefined | null;
+interface URLObject {
+    base: string;
+    query: Record<string, QueryValue>;
+    hash: string;
+}
+export declare function urlParse(url?: string): URLObject;
+export declare function urlStringify(opts: Partial<URLObject>, omitNil?: boolean): string;
+export {};

package/dist/url/index.js

@@ -0,0 +1,28 @@
+import { isNullish as e } from "../node_modules/.pnpm/remeda@2.39.0/node_modules/remeda/dist/isNullish.js";
+import { omitBy as t } from "../node_modules/.pnpm/remeda@2.39.0/node_modules/remeda/dist/omitBy.js";
+//#region src/url/index.ts
+function n(e = "") {
+	let t = !/^(https?:)?\/\//.test(e);
+	try {
+		let n = new URL(e, t ? "http://n.n" : void 0);
+		return {
+			base: t ? n.pathname : `${n.origin}${n.pathname}`,
+			query: Object.fromEntries(n.searchParams),
+			hash: n.hash
+		};
+	} catch {
+		throw Error("Invalid URL.");
+	}
+}
+function r(n, r = !0) {
+	let { base: i = "", query: a = {}, hash: o = "" } = n, s = r ? t(a, e) : a, c = new URLSearchParams();
+	Object.entries(s).forEach(([e, t]) => {
+		c.append(e, String(t));
+	});
+	let l = o ? o.startsWith("#") ? o : `#${o}` : "", u = c.toString();
+	return u ? `${i}${i.includes("?") ? "&" : "?"}${u}${l}` : i + l;
+}
+//#endregion
+export { n as urlParse, r as urlStringify };
+
+//# sourceMappingURL=index.js.map

package/dist/url/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/url/index.ts"],"sourcesContent":["import { isNullish, omitBy } from 'remeda'\n\ntype QueryValue = string | number | boolean | undefined | null\ninterface URLObject {\n  base: string\n  query: Record<string, QueryValue>\n  hash: string\n}\n\nexport function urlParse(url = ''): URLObject {\n  const isRelative = !/^(https?:)?\\/\\//.test(url)\n\n  try {\n    // 如果 url 是相对路径，就借用 http://n.n 作为 base\n    const parsed = new URL(url, isRelative ? 'http://n.n' : undefined)\n\n    return {\n      base: isRelative ? parsed.pathname : `${parsed.origin}${parsed.pathname}`,\n      query: Object.fromEntries(parsed.searchParams),\n      hash: parsed.hash\n    }\n  } catch {\n    throw new Error('Invalid URL.')\n  }\n}\n\nexport function urlStringify(opts: Partial<URLObject>, omitNil = true): string {\n  const { base = '', query = {}, hash = '' } = opts\n\n  const cleanQuery = omitNil ? omitBy(query, isNullish) : query\n  const params = new URLSearchParams()\n\n  Object.entries(cleanQuery).forEach(([key, val]) => {\n    params.append(key, String(val))\n  })\n\n  // 修复 Hash 自动补全 # 的问题\n  const normalizedHash = hash ? (hash.startsWith('#') ? hash : `#${hash}`) : ''\n  const queryString = params.toString()\n  if (!queryString) return base + normalizedHash\n\n  const connector = base.includes('?') ? '&' : '?'\n  return `${base}${connector}${queryString}${normalizedHash}`\n}\n"],"mappings":";;;AASA,SAAgB,EAAS,IAAM,IAAe;CAC5C,IAAM,IAAa,CAAC,kBAAkB,KAAK,CAAG;CAE9C,IAAI;EAEF,IAAM,IAAS,IAAI,IAAI,GAAK,IAAa,eAAe,KAAA,CAAS;EAEjE,OAAO;GACL,MAAM,IAAa,EAAO,WAAW,GAAG,EAAO,SAAS,EAAO;GAC/D,OAAO,OAAO,YAAY,EAAO,YAAY;GAC7C,MAAM,EAAO;EACf;CACF,QAAQ;EACN,MAAU,MAAM,cAAc;CAChC;AACF;AAEA,SAAgB,EAAa,GAA0B,IAAU,IAAc;CAC7E,IAAM,EAAE,UAAO,IAAI,WAAQ,CAAC,GAAG,UAAO,OAAO,GAEvC,IAAa,IAAU,EAAO,GAAO,CAAS,IAAI,GAClD,IAAS,IAAI,gBAAgB;CAEnC,OAAO,QAAQ,CAAU,CAAC,CAAC,SAAS,CAAC,GAAK,OAAS;EACjD,EAAO,OAAO,GAAK,OAAO,CAAG,CAAC;CAChC,CAAC;CAGD,IAAM,IAAiB,IAAQ,EAAK,WAAW,GAAG,IAAI,IAAO,IAAI,MAAU,IACrE,IAAc,EAAO,SAAS;CAIpC,OAHK,IAGE,GAAG,IADQ,EAAK,SAAS,GAAG,IAAI,MAAM,MAChB,IAAc,MAHlB,IAAO;AAIlC"}

package/dist/utility-types/index.d.ts

@@ -0,0 +1,13 @@
+export type ValueOf<T> = T[keyof T];
+export type ArrayItem<T extends unknown[]> = T extends (infer R)[] ? R : never;
+export type ArgumentType<T> = T extends (...args: (infer R)[]) => unknown ? R : never;
+export type DeepPartial<T> = Partial<{
+    [K in keyof T]: DeepPartial<T[K]>;
+}>;
+export type DeepRequired<T> = Required<{
+    [K in keyof T]: DeepRequired<T[K]>;
+}>;
+export type ClassPropertyTypes<T> = {
+    [K in keyof T]: T[K];
+};
+export type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2 ? true : false;

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@greypan/js-kit",
+  "version": "1.0.0",
+  "description": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pan-Z2l0aHVi/mono.git"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./*": {
+      "types": "./dist/*/index.d.ts",
+      "import": "./dist/*/index.js"
+    },
+    "./go": {
+      "types": "./dist/paradigm/go.d.ts",
+      "import": "./dist/paradigm/go.js"
+    },
+    "./rust": {
+      "types": "./dist/paradigm/rust.d.ts",
+      "import": "./dist/paradigm/rust.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "vite": "npm:@voidzero-dev/vite-plus-core@latest",
+    "vite-plus": "latest"
+  },
+  "browserslist": [
+    "defaults"
+  ],
+  "scripts": {
+    "build": "run-p type-check \"build-only {@}\" --",
+    "build-only": "vp build",
+    "deploy": "npm publish",
+    "preview": "vp preview",
+    "test": "vp test run",
+    "type-check": "vue-tsc --build",
+    "dev": "vp build --watch"
+  }
+}

package/src/fetch/__tests__/compose.spec.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vite-plus/test'
+
+import { asyncCompose, type Middleware } from '../compose'
+
+describe('Compose 单元测试', () => {
+  describe('基本用法', () => {
+    it('应当按顺序运行中间件', async () => {
+      const calls: string[] = []
+
+      const middleware1: Middleware = async (ctx, next) => {
+        calls.push('m1-before')
+        await next()
+        calls.push('m1-after')
+      }
+      const middleware2: Middleware = async (ctx, next) => {
+        calls.push('m2-before')
+        await next()
+        calls.push('m2-after')
+      }
+      const middleware3: Middleware = async (ctx, next) => {
+        calls.push('m3')
+        await next()
+      }
+
+      const fn = asyncCompose(middleware1, middleware2, middleware3)
+
+      await fn({}, async () => {
+        calls.push('end')
+      })
+
+      expect(calls).toEqual(['m1-before', 'm2-before', 'm3', 'end', 'm2-after', 'm1-after'])
+    })
+  })
+
+  describe('compose 边界情况', () => {
+    it('空中间件数组时应直接调用外层 next', async () => {
+      const calls: string[] = []
+      const fn = asyncCompose()
+      await fn({}, async () => {
+        calls.push('end')
+      })
+      expect(calls).toEqual(['end'])
+    })
+
+    it('单个中间件时应正常执行并调用外层 next', async () => {
+      const calls: string[] = []
+      const fn = asyncCompose(async (ctx, next) => {
+        calls.push('single')
+        await next()
+      })
+      await fn({}, async () => {
+        calls.push('end')
+      })
+      expect(calls).toEqual(['single', 'end'])
+    })
+
+    it('多次调用同一个 compose 函数时索引不应污染', async () => {
+      const fn = asyncCompose(
+        async (ctx: { calls: string[] }, next) => {
+          ctx.calls.push('m1')
+          await next()
+        },
+        async (ctx: { calls: string[] }, next) => {
+          ctx.calls.push('m2')
+          await next()
+        }
+      )
+      const calls1: string[] = []
+      const calls2: string[] = []
+      await fn({ calls: calls1 }, async () => {
+        calls1.push('end')
+      })
+      await fn({ calls: calls2 }, async () => {
+        calls2.push('end')
+      })
+      expect(calls1).toEqual(['m1', 'm2', 'end'])
+      expect(calls2).toEqual(['m1', 'm2', 'end'])
+    })
+
+    it('中间件抛出错误时应正确传递异常', async () => {
+      const fn = asyncCompose(
+        async () => {
+          throw new Error('boom')
+        },
+        async (ctx, next) => {
+          await next()
+        }
+      )
+      await expect(fn({}, async () => {})).rejects.toThrow('boom')
+    })
+
+    it('同一个中间件里重复调用 next 应该抛错', async () => {
+      const fn = asyncCompose(
+        async (ctx, next) => {
+          await next()
+          await next() // 第二次调用，触发防护
+        },
+        async (ctx, next) => {
+          await next()
+        }
+      )
+      await expect(fn({}, async () => {})).rejects.toThrow('Should not call "await next()" multiple times!')
+    })
+  })
+})

package/src/fetch/compose.ts

@@ -0,0 +1,23 @@
+export type Next = () => Promise<void>
+export type Middleware<T = unknown> = (ctx: T, next: Next) => Promise<void>
+
+export function asyncCompose<T = unknown>(...fns: Middleware<T>[]): Middleware<T> {
+  return async function dispatch(ctx: T, next: Next, i = 0): Promise<void> {
+    if (!fns.length) return next()
+    const fn = fns[i]
+    if (!fn) return next()
+    return fn(
+      ctx,
+      // 为什么不是 () => dispatch(ctx, next, i + 1)？
+      // 利用闭包防止中间件重复调用 next
+      (() => {
+        let called = false
+        return async () => {
+          if (called) throw new Error('Should not call "await next()" multiple times!')
+          called = true
+          await dispatch(ctx, next, i + 1)
+        }
+      })()
+    )
+  }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from './number'
+export * from './paradigm'
+export * from './plugin'
+export * from './random'
+export * from './timer'
+export * from './url'
+export * from './utility-types'

package/src/number/__tests__/number.spec.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vite-plus/test'
+
+import { clamp, toPrecision } from '..'
+
+describe('number 单元测试', () => {
+  describe('toPrecision', () => {
+    it('应正确处理正数精度（四舍五入）', () => {
+      expect(toPrecision(1234.567, 2)).toBe(1234.57)
+      expect(toPrecision(1.45, 1)).toBe(1.5)
+      expect(toPrecision(1.44, 1)).toBe(1.4)
+    })
+
+    it('应正确处理负数精度（取整到十位/百位）', () => {
+      expect(toPrecision(1234.56, -1)).toBe(1230)
+      expect(toPrecision(1234.56, -2)).toBe(1200)
+      expect(toPrecision(1260.56, -2)).toBe(1300)
+    })
+
+    it('应正确处理精度为 0 的情况', () => {
+      expect(toPrecision(1234.56, 0)).toBe(1235)
+    })
+
+    it('应对非有限数字（NaN, Infinity）原样返回', () => {
+      expect(toPrecision(NaN, 2)).toBeNaN()
+      expect(toPrecision(Infinity, 2)).toBe(Infinity)
+      expect(toPrecision(-Infinity, 2)).toBe(-Infinity)
+    })
+  })
+
+  describe('clamp', () => {
+    it('数值在范围内时应返回原值', () => {
+      expect(clamp(5, 0, 10)).toBe(5)
+      expect(clamp(0, 0, 10)).toBe(0)
+      expect(clamp(10, 0, 10)).toBe(10)
+    })
+
+    it('数值小于最小值时应返回最小值', () => {
+      expect(clamp(-5, 0, 10)).toBe(0)
+    })
+
+    it('数值大于最大值时应返回最大值', () => {
+      expect(clamp(15, 0, 10)).toBe(10)
+    })
+
+    it('处理负数区间', () => {
+      expect(clamp(-20, -10, -5)).toBe(-10)
+      expect(clamp(-2, -10, -5)).toBe(-5)
+    })
+  })
+})

package/src/number/index.ts

@@ -0,0 +1,22 @@
+/**
+ * 转换为指定精度的数字
+ * @param val 需要转换的数字
+ * @param precision 精度。表示小数点后位数。如果传了负数（比如 -2），则取整到百位（1234.56->1200）。
+ * @returns 转换后的数字
+ */
+export function toPrecision(val: number, precision: number): number {
+  if (Number.isNaN(val) || !Number.isFinite(val)) return val
+
+  const factor = Math.pow(10, precision)
+  return Math.round(val * factor) / factor
+}
+
+/**
+ * 将数字限制在指定的范围内
+ * @param val 当前值
+ * @param min 最小值
+ * @param max 最大值
+ */
+export function clamp(val: number, min: number, max: number): number {
+  return Math.max(min, Math.min(val, max))
+}

package/src/paradigm/__tests__/go.spec.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vite-plus/test'
+
+import { err, isErr, isOk, ok, to, unwrap } from '../go'
+
+describe('Result 工具函数（Go 风格）单元测试', () => {
+  it('ok() 应当返回 Ok<T>', () => {
+    const result = ok(42)
+    expect(result).toEqual([null, 42])
+    expect(isOk(result)).toBe(true)
+    expect(isErr(result)).toBe(false)
+  })
+
+  it('err() 应当返回 Err<E>', () => {
+    const error = new Error('Failed.')
+    const result = err(error)
+    expect(result).toEqual([error, null])
+    expect(isErr(result)).toBe(true)
+    expect(isOk(result)).toBe(false)
+  })
+
+  it('isOk() 和 isErr() 应当正确区分结果', () => {
+    const success = ok(123)
+    const failure = err('error')
+
+    expect(isOk(success)).toBe(true)
+    expect(isErr(success)).toBe(false)
+
+    expect(isOk(failure)).toBe(false)
+    expect(isErr(failure)).toBe(true)
+  })
+
+  it('to() 应当把成功的 Promise 包装成 Ok', async () => {
+    const result = await to(Promise.resolve('hi'))
+    expect(isOk(result)).toBe(true)
+    expect(result).toEqual([null, 'hi'])
+  })
+
+  it('to() 应当把失败的 Promise 包装成 Err', async () => {
+    const result = await to(Promise.reject('error'))
+    expect(isErr(result)).toBe(true)
+    expect(result).toEqual(['error', null])
+  })
+
+  it('unwrap() 在 Ok 时返回值', () => {
+    const result = ok('data')
+    expect(unwrap(result)).toBe('data')
+  })
+
+  it('unwrap() 在 Err 时返回错误', () => {
+    const result = err('error')
+    expect(unwrap(result)).toBe('error')
+  })
+
+  it('Result 数据结构应当是 [error, value]', () => {
+    const success = ok(1)
+    expect(success[0]).toBeNull()
+    expect(success[1]).toBe(1)
+
+    const failure = err('boom')
+    expect(failure[0]).toBe('boom')
+    expect(failure[1]).toBeNull()
+  })
+})

package/src/paradigm/__tests__/rust.spec.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vite-plus/test'
+
+import { err, isErr, isOk, ok, to, unwrap } from '../rust'
+
+describe('Result 工具函数（Rust 风格）单元测试', () => {
+  it('ok() 应当返回一个 Ok<T>', () => {
+    const result = ok(123)
+    expect(result).toEqual({ ok: true, value: 123 })
+    expect(isOk(result)).toBe(true)
+    expect(isErr(result)).toBe(false)
+  })
+
+  it('err() 应当返回一个 Err<E>', () => {
+    const result = err('error')
+    expect(result).toEqual({ ok: false, error: 'error' })
+    expect(isErr(result)).toBe(true)
+    expect(isOk(result)).toBe(false)
+  })
+
+  it('isOk() 和 isErr() 应当正确区分结果', () => {
+    const success = ok('success')
+    const failure = err('fail')
+
+    expect(isOk(success)).toBe(true)
+    expect(isErr(success)).toBe(false)
+
+    expect(isOk(failure)).toBe(false)
+    expect(isErr(failure)).toBe(true)
+  })
+
+  it('to() 应当把成功的 Promise 包装成 Ok', async () => {
+    const result = await to(Promise.resolve('data'))
+    expect(result).toEqual({ ok: true, value: 'data' })
+    expect(isOk(result)).toBe(true)
+  })
+
+  it('to() 应当把失败的 Promise 包装成 Err', async () => {
+    const result = await to(Promise.reject('error'))
+    expect(result).toEqual({ ok: false, error: 'error' })
+    expect(isErr(result)).toBe(true)
+  })
+
+  it('unwrap() 在 Ok 时返回值', () => {
+    const result = ok('data')
+    expect(unwrap(result)).toBe('data')
+  })
+
+  it('unwrap() 在 Err 时返回错误', () => {
+    const result = err('error')
+    expect(unwrap(result)).toBe('error')
+  })
+
+  it('Ok<T> 应当只有 ok 和 value 属性，没有 error', () => {
+    const result = ok('success')
+    expect(result).toHaveProperty('ok')
+    expect(result.ok).toBe(true)
+    expect(result).toHaveProperty('value')
+    expect(result).not.toHaveProperty('error')
+  })
+
+  it('Err<E> 应当只有 ok 和 error 属性，没有 value', () => {
+    const result = err('fail')
+    expect(result).toHaveProperty('ok')
+    expect(result.ok).toBe(false)
+    expect(result).toHaveProperty('error')
+    expect(result).not.toHaveProperty('value')
+  })
+})

package/src/paradigm/go.ts

@@ -0,0 +1,38 @@
+/**
+ * @description Go 范式，用于统一处理成功/失败返回值
+ */
+
+export type Ok<T> = readonly [null, T]
+export type Err<E> = readonly [E, null]
+export type Result<T, E> = Ok<T> | Err<E>
+
+export function ok<T>(value: T): Ok<T> {
+  return [null, value]
+}
+
+export function err<E>(error: E): Err<E> {
+  return [error, null]
+}
+
+export function isOk<T, E>(result: Result<T, E>): result is Ok<T> {
+  return result[0] === null && result[1] !== null
+}
+
+export function isErr<T, E>(result: Result<T, E>): result is Err<E> {
+  return result[0] !== null && result[1] === null
+}
+
+export async function to<T, E = unknown>(promise: Promise<T>): Promise<Result<Awaited<T>, E>> {
+  try {
+    return ok(await promise)
+  } catch (error) {
+    return err(error as E)
+  }
+}
+
+export function unwrap<S extends Result<any, any>>(
+  result: S
+): S extends Ok<infer T> ? T : S extends Err<infer E> ? E : never {
+  const [error, value] = result
+  return isOk(result) ? value : error
+}

package/src/paradigm/index.ts

@@ -0,0 +1,2 @@
+export * as go from './go'
+export * as rust from './rust'