@greypan/js-kit 1.0.0

package/src/paradigm/rust.ts

@@ -0,0 +1,50 @@
+/**
+ * @description Rust 范式，用于统一处理成功/失败返回值
+ */
+
+export type Ok<T> = {
+  readonly ok: true
+  readonly value: T
+}
+export type Err<E> = {
+  readonly ok: false
+  readonly error: E
+}
+/**
+ * 考虑到 T 或 E 其中一个为 never 的情况
+ * Result<T,never> 等价于 Ok<T>
+ * Result<never,E> 等价于 Err<E>
+ * 为什么是 [T] extends [never] ? 而不是 T extends never ?：
+ * 条件类型是分布式的，防止 T 为联合类型时对每项分别计算再合并结果
+ */
+export type Result<T, E> = Ok<T> | Err<E>
+
+export function ok<T>(value: T): Ok<T> {
+  return { ok: true, value }
+}
+
+export function err<E>(error: E): Err<E> {
+  return { ok: false, error }
+}
+
+export function isOk<T, E>(result: Result<T, E>): result is Ok<T> {
+  return result.ok
+}
+
+export function isErr<T, E>(result: Result<T, E>): result is Err<E> {
+  return !result.ok
+}
+
+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 {
+  return result.ok ? result.value : result.error
+}

package/src/plugin/__tests__/batch-emitter.spec.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it, vi } from 'vite-plus/test'
+
+import { defineBatchEmitter } from '..'
+
+describe('BatchEmitter 单元测试', () => {
+  it('立即返回单个 id，当 delay <= 0', async () => {
+    const batchEmitter = defineBatchEmitter().make()
+    const { batchEmit } = batchEmitter
+    const result = await batchEmit('a', 0)
+    expect(result).toEqual(['a'])
+  })
+
+  it('延迟后批量返回多个 id', async () => {
+    const batchEmitter = defineBatchEmitter().make()
+    const { batchEmit } = batchEmitter
+    const p1 = batchEmit('a', 10)
+    const p2 = batchEmit('b', 10)
+    const p3 = batchEmit('c', 10)
+
+    const results = await Promise.all([p1, p2, p3])
+    // 三个 promise 都应该 resolve 同一个批次
+    results.forEach(r => expect(r).toEqual(['a', 'b', 'c']))
+  })
+
+  it('flush 可以同步清空队列并调用 onFlushed', async () => {
+    const onFlushed = vi.fn()
+    const batchEmitter = defineBatchEmitter(onFlushed).make()
+    const { batchEmit, flush } = batchEmitter
+
+    const p1 = batchEmit(1, 100)
+    const p2 = batchEmit(2, 100)
+
+    await flush()
+
+    const results = await Promise.all([p1, p2])
+    expect(results[0]).toEqual([1, 2])
+    expect(results[1]).toEqual([1, 2])
+    expect(onFlushed).toHaveBeenCalledWith([1, 2])
+  })
+
+  it('flush 在队列为空时不做任何事', async () => {
+    const onFlushed = vi.fn()
+    const batchEmitter = defineBatchEmitter(onFlushed).make()
+    const { flush } = batchEmitter
+    await flush()
+    expect(onFlushed).not.toHaveBeenCalled()
+  })
+})

package/src/plugin/__tests__/core.spec.ts

@@ -0,0 +1,110 @@
+import { beforeEach, describe, expect, it, vi } from 'vite-plus/test'
+
+import { definePlugin, type PluginMade } from '../core'
+
+describe('definePlugin 单元测试', () => {
+  const localStorageMock = (() => {
+    let store: Record<string, string> = {}
+    return {
+      getItem: (key: string) => store[key] || null,
+      setItem: (key: string, value: string) => {
+        store[key] = value.toString()
+      },
+      clear: () => {
+        store = {}
+      }
+    }
+  })()
+  vi.stubGlobal('localStorage', localStorageMock)
+
+  beforeEach(() => {
+    localStorage.clear()
+    vi.restoreAllMocks()
+  })
+
+  describe('make', () => {
+    it('应当实例化插件，并且能够调用插件的属性方法', () => {
+      function defineTracker() {
+        return definePlugin(() => ({
+          track: (event: string) => console.log(`tracking ${event}`)
+        }))
+      }
+      const tracker = defineTracker().make()
+      expect(tracker).toHaveProperty('track')
+      expect(typeof tracker.track).toBe('function')
+
+      const spy = vi.spyOn(console, 'log').mockImplementation(() => {})
+      tracker.track('test event')
+      expect(spy).toHaveBeenCalled()
+    })
+  })
+
+  describe('use', () => {
+    const defineStore = (initial: Record<string, number>) =>
+      definePlugin(() => {
+        let store: Record<string, number> = initial
+        return {
+          setStore(newStore: Record<string, number>) {
+            store = newStore
+          },
+          get(key: string) {
+            return store[key]
+          },
+          set(key: string, val: number) {
+            store[key] = val
+          }
+        }
+      })
+
+    const defineLogger = () =>
+      definePlugin((ctx: PluginMade<typeof defineStore>) => ({
+        set: (key: string, val: number) => {
+          ctx.set(key, val)
+          console.log(`set ${key} = ${val}.`)
+        }
+      }))
+
+    const definePersist = (persitKey = 'persit-store') =>
+      definePlugin((ctx: PluginMade<typeof defineStore>) => {
+        const cache = localStorage.getItem(persitKey)
+        if (cache) ctx.setStore(JSON.parse(cache))
+        return {
+          setStore(newStore: Record<string, number>) {
+            ctx.setStore(newStore)
+            localStorage.setItem(persitKey, JSON.stringify(newStore))
+          },
+          set(key: string, val: number) {
+            ctx.set(key, val)
+            const cache: Record<string, number> = JSON.parse(localStorage.getItem(persitKey) ?? '{}')
+            cache[key] = val
+            localStorage.setItem(persitKey, JSON.stringify(cache))
+          }
+        }
+      })
+
+    it('应当正确组合 Store, Logger 和 Persist 逻辑', () => {
+      const logSpy = vi.spyOn(console, 'log')
+
+      const store = defineStore({ a: 1, b: 2 }).use(defineLogger()).use(definePersist()).make()
+
+      expect(store.get('a')).toBe(1)
+
+      // 调用顺序: Persist.set -> Logger.set -> Store.set
+      store.set('a', 100)
+
+      expect(store.get('a')).toBe(100)
+      expect(logSpy).toHaveBeenCalledWith('set a = 100.')
+
+      const cached = JSON.parse(localStorage.getItem('persit-store') || '{}')
+      expect(cached.a).toBe(100)
+    })
+
+    it('应当在初始化时从持久化恢复数据', () => {
+      localStorage.setItem('persit-store', JSON.stringify({ a: 999 }))
+
+      const store = defineStore({ a: 1 }).use(definePersist()).make()
+
+      expect(store.get('a')).toBe(999)
+    })
+  })
+})

package/src/plugin/__tests__/event-emiiter.spec.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it, vi } from 'vite-plus/test'
+
+import { defineEventEmitter } from '../event-emitter'
+
+describe('EventEmitter 单元测试', () => {
+  it('应当支持注册和触发事件回调', () => {
+    const logSpy = vi.spyOn(console, 'log')
+
+    const eventEmitter = defineEventEmitter<{
+      click: [string]
+    }>().make()
+    eventEmitter.on('click', e => {
+      console.log(`${e} click 1`)
+    })
+    eventEmitter.on('click', e => {
+      console.log(`${e} click 2`)
+    })
+    eventEmitter.emit('click', 'Tom')
+
+    expect(logSpy).toHaveBeenCalledWith('Tom click 1')
+    expect(logSpy).toHaveBeenCalledWith('Tom click 2')
+  })
+
+  it('应当支持传递 rest 参数', () => {
+    const eventPlugin = defineEventEmitter<{
+      'user:update': [number, string, 'admin' | 'user']
+      'app:start': []
+    }>()
+    const app = eventPlugin.make()
+    const users: string[] = []
+
+    app.on('user:update', (id, name, role) => {
+      const user = `ID: ${id}, Name: ${name}, Role: ${role}`
+      users.push(user)
+    })
+
+    app.emit('user:update', 1, 'Tom', 'admin')
+
+    expect(users).toEqual(['ID: 1, Name: Tom, Role: admin'])
+  })
+})

package/src/plugin/batching-emitter.ts

@@ -0,0 +1,61 @@
+import { definePlugin } from './core'
+
+type Resolve<S> = (queue: S[]) => void
+
+export function defineBatchEmitter<S>(onFlushed?: (queue: S[]) => Promise<void>) {
+  return definePlugin(() => {
+    let queue: S[] = []
+    let resolves: Resolve<S>[] = []
+    let timerId: ReturnType<typeof setTimeout> | null = null
+
+    /**
+     * 批量发出，延迟执行
+     */
+    async function batchEmit(data: S, batchingDelay = 0): Promise<S[]> {
+      if (batchingDelay <= 0) {
+        if (onFlushed) await onFlushed([data])
+        return Promise.resolve([data])
+      }
+
+      return new Promise((resolve, reject) => {
+        resolves.push(resolve)
+
+        if (queue.push(data) === 1) {
+          timerId = setTimeout(() => {
+            try {
+              void flush()
+            } catch (error) {
+              reject(error)
+            }
+          }, batchingDelay)
+        }
+      })
+    }
+
+    /**
+     * 立即清空并执行当前的队列
+     */
+    async function flush() {
+      if (!queue.length) return
+
+      // 先快照一份，防止后续 push 污染当前批次，消除异步重入（Re-entrancy）
+      const currentQueue = [...queue]
+      const currentResolves = [...resolves]
+      queue = []
+      resolves = []
+      if (timerId) {
+        clearTimeout(timerId)
+        timerId = null
+      }
+
+      if (onFlushed) await onFlushed(currentQueue)
+
+      let fn: Resolve<S> | undefined
+      while ((fn = currentResolves.shift())) {
+        fn(currentQueue)
+      }
+    }
+
+    return { batchEmit, flush }
+  })
+}

package/src/plugin/core.ts

@@ -0,0 +1,37 @@
+export interface Plugin<C extends object, D extends object> {
+  readonly use: <U extends object, E extends object>(plugin: Plugin<U, E>) => Plugin<C & U, D & E>
+  readonly make: <T extends D>(ctx?: T) => T & C
+}
+
+export function definePlugin<C extends object, D extends object>(setup: (ctx: D) => C): Plugin<C, D> {
+  function use<U extends object, E extends object>(plugin: Plugin<U, E>): Plugin<C & U, D & E> {
+    return definePlugin<C & U, D & E>(ctx => {
+      return plugin.make({
+        ...ctx,
+        ...setup(ctx)
+      })
+    })
+  }
+
+  function make<T extends D>(ctx = {} as T): T & C {
+    return {
+      ...ctx,
+      ...setup(ctx)
+    }
+  }
+
+  return {
+    use,
+    make
+  }
+}
+
+/**
+ * 提取插件实例化的类型 (C & D)
+ * T 可以是 Plugin 实例，也可以是返回 Plugin 实例的函数
+ */
+export type PluginMade<T> = T extends (...args: any[]) => Plugin<infer C, infer D>
+  ? C & D
+  : T extends Plugin<infer C, infer D>
+    ? C & D
+    : never

package/src/plugin/event-emitter.ts

@@ -0,0 +1,25 @@
+import { definePlugin } from './core'
+
+export function defineEventEmitter<E extends Record<string, unknown[]>>() {
+  return definePlugin(() => {
+    const bus = new EventTarget()
+
+    return {
+      on<K extends keyof E>(type: K & string, handler: (...args: E[K]) => void, options?: AddEventListenerOptions) {
+        const listener = (e: Event) => {
+          const args = (e as CustomEvent).detail as E[K]
+          handler(...args)
+        }
+        bus.addEventListener(type, listener, options)
+        // off fn
+        return () => bus.removeEventListener(type, listener)
+      },
+
+      // 支持传入多个参数
+      emit<K extends keyof E>(type: K & string, ...args: E[K]) {
+        const event = new CustomEvent(type, { detail: args })
+        bus.dispatchEvent(event)
+      }
+    }
+  })
+}

package/src/plugin/index.ts

@@ -0,0 +1,2 @@
+export * from './batching-emitter'
+export * from './core'

package/src/random/__tests__/random.spec.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'vite-plus/test'
+
+import { randomFloat, randomHex, randomRgb } from '..'
+
+describe('random 单元测试', () => {
+  describe('randomFloat', () => {
+    it('结果应在指定的范围内', () => {
+      const min = 1.1
+      const max = 5.5
+      for (let i = 0; i < 100; i++) {
+        const result = randomFloat(min, max)
+        expect(result).toBeGreaterThanOrEqual(min)
+        // 考虑到 Math.random() 是 [0, 1)，结果理论上小于 max
+        expect(result).toBeLessThanOrEqual(max)
+      }
+    })
+
+    it('即便 min 和 max 传反了也应当正常工作', () => {
+      const min = 10
+      const max = 1
+      const result = randomFloat(min, max)
+      expect(result).toBeGreaterThanOrEqual(1)
+      expect(result).toBeLessThanOrEqual(10)
+    })
+
+    it('当 min 等于 max 时应返回该数值', () => {
+      const result = randomFloat(5, 5)
+      expect(result).toBe(5)
+    })
+  })
+
+  describe('randomRgb', () => {
+    it('应当返回正确的 rgb(r, g, b) 格式', () => {
+      // 允许逗号后有或没有空格
+      const rgbRegex = /^rgb\(\d{1,3},\s?\d{1,3},\s?\d{1,3}\)$/
+      for (let i = 0; i < 50; i++) {
+        const result = randomRgb()
+        expect(result).toMatch(rgbRegex)
+
+        // 进一步校验数值范围
+        const colors = result.match(/\d+/g)?.map(Number)
+        colors?.forEach(c => {
+          expect(c).toBeGreaterThanOrEqual(0)
+          expect(c).toBeLessThanOrEqual(255)
+        })
+      }
+    })
+  })
+
+  describe('randomHex', () => {
+    it('应当返回正确的十六进制格式', () => {
+      const hexRegex = /^#[0-9a-f]{6}$/
+      for (let i = 0; i < 50; i++) {
+        const result = randomHex()
+        expect(result).toMatch(hexRegex)
+      }
+    })
+
+    it('生成的十六进制应当是小写的', () => {
+      const result = randomHex()
+      // 检查不含大写字母：如果包含大写字母则测试失败
+      expect(result).not.toMatch(/[A-Z]/)
+    })
+  })
+
+  describe('随机性校验 (Randomness)', () => {
+    it('连续调用不应产生相同的结果', () => {
+      const results = new Set()
+      const count = 100
+      for (let i = 0; i < count; i++) {
+        results.add(randomHex())
+      }
+      // 16777216 种颜色选 100 次，碰撞概率微乎其微
+      expect(results.size).toBe(count)
+    })
+  })
+})

package/src/random/index.ts

@@ -0,0 +1,37 @@
+/**
+ * 随机整数 [min, max]
+ * @param min 最小值
+ * @param max 最大值
+ */
+export function random(min: number, max: number): number {
+  return Math.floor(Math.random() * (max - min + 1)) + min
+}
+
+/**
+ * 随机浮点数 [min, max)
+ * @param min 最小值
+ * @param max 最大值
+ * @param precision 保留小数位，不传则返回原始浮点数
+ */
+export function randomFloat(min: number, max: number): number {
+  const lower = Math.min(min, max)
+  const upper = Math.max(min, max)
+  return lower + Math.random() * (upper - lower)
+}
+
+/**
+ * 生成随机的 RGB 颜色代码
+ * @returns RGB 颜色代码，例如 rgb(255, 0, 0)
+ */
+export function randomRgb(): string {
+  return `rgb(${random(0, 255)}, ${random(0, 255)}, ${random(0, 255)})`
+}
+
+/**
+ * 生成随机的十六进制颜色代码
+ * @returns 十六进制颜色代码，例如 #ff0000
+ */
+export function randomHex(): string {
+  const color = Math.floor(Math.random() * 0x1000000).toString(16)
+  return '#' + color.padStart(6, '0')
+}

package/src/timer/__tests__/controllable-interval.spec.ts

@@ -0,0 +1,51 @@
+import { beforeEach, describe, expect, it, vi } from 'vite-plus/test'
+
+import { createControllableInterval } from '..'
+
+describe('timer 单元测试', () => {
+  describe('ControllableInterval', () => {
+    beforeEach(() => {
+      vi.useFakeTimers()
+    })
+
+    it('应当能正常循环执行', () => {
+      const cb = vi.fn()
+      const timer = createControllableInterval(cb, 1000)
+      timer.start()
+
+      vi.advanceTimersByTime(3500)
+      expect(cb).toHaveBeenCalledTimes(3)
+      timer.stop()
+    })
+
+    it('暂停后不应触发回调', () => {
+      const cb = vi.fn()
+      const timer = createControllableInterval(cb, 1000)
+      timer.start()
+
+      vi.advanceTimersByTime(500)
+      timer.pause()
+      vi.advanceTimersByTime(1000)
+
+      expect(cb).not.toHaveBeenCalled()
+      timer.stop()
+    })
+
+    it('恢复后应先补全剩余时间', () => {
+      const cb = vi.fn()
+      const timer = createControllableInterval(cb, 1000)
+      timer.start()
+
+      vi.advanceTimersByTime(800) // 此时还剩 200ms
+      timer.pause()
+
+      timer.resume()
+      vi.advanceTimersByTime(150)
+      expect(cb).not.toHaveBeenCalled() // 还没到 200ms，不触发
+
+      vi.advanceTimersByTime(60) // 超过 200ms 了
+      expect(cb).toHaveBeenCalledTimes(1)
+      timer.stop()
+    })
+  })
+})

package/src/timer/controllable-interval.ts

@@ -0,0 +1,86 @@
+/**
+ * @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)
+ */
+
+import { definePlugin } from '@/plugin'
+
+export function defineControllableInterval(callback: () => void, interval: number) {
+  return definePlugin(() => {
+    let timerId: ReturnType<typeof setTimeout> | null = null
+    let isPaused = false
+    let remainingTime = 0
+    let lastStartTime = 0
+
+    function tick(delay: number) {
+      lastStartTime = Date.now()
+      timerId = setTimeout(() => {
+        callback()
+        // 只有在没被暂停的情况下，才继续下一次循环
+        if (!isPaused) tick(interval)
+      }, delay)
+    }
+
+    function start() {
+      if (timerId || isPaused) return
+
+      tick(interval)
+    }
+
+    function pause() {
+      if (isPaused || !timerId) return
+
+      isPaused = true
+      clearTimeout(timerId)
+      timerId = null
+
+      // 计算当前这一轮还剩多少时间没跑完
+      const diff = Date.now() - lastStartTime
+      remainingTime = Math.max(0, interval - diff)
+    }
+
+    function resume() {
+      if (!isPaused) return
+
+      isPaused = false
+      // 恢复执行：先跑完上一轮剩下的时间
+      tick(remainingTime || interval)
+    }
+
+    function stop() {
+      if (timerId) clearTimeout(timerId)
+
+      timerId = null
+      isPaused = false
+      remainingTime = 0
+    }
+
+    return {
+      tick,
+      start,
+      pause,
+      resume,
+      stop
+    }
+  })
+}
+
+export function createControllableInterval(callback: () => void, interval: number) {
+  return defineControllableInterval(callback, interval).make()
+}