@greypan/js-kit 1.0.0 → 1.2.0

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

@@ -1,68 +0,0 @@
-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

@@ -1,38 +0,0 @@
-/**
- * @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

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

package/src/paradigm/rust.ts

@@ -1,50 +0,0 @@
-/**
- * @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

@@ -1,48 +0,0 @@
-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

@@ -1,110 +0,0 @@
-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

@@ -1,41 +0,0 @@
-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

@@ -1,61 +0,0 @@
-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

@@ -1,37 +0,0 @@
-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

@@ -1,25 +0,0 @@
-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

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

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

@@ -1,77 +0,0 @@
-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

@@ -1,37 +0,0 @@
-/**
- * 随机整数 [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

@@ -1,51 +0,0 @@
-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()
-    })
-  })
-})