@planet-matrix/mobius-model 0.3.0 → 0.4.0

package/tests/unit/basic/function.spec.ts

@@ -0,0 +1,175 @@
+import { expect, test, vi } from "vitest"
+
+import {
+  debounce,
+  functionCompose,
+  functionDebounceSimple,
+  functionIife,
+  functionMemorize,
+  functionOnce,
+  functionPipe,
+  functionThrottle,
+  functionThrottleSimple,
+  functionThrottleTimeSimple,
+  throttleTime,
+} from "#Source/basic/index.ts"
+
+test("functionIife invokes immediately", () => {
+  expect(functionIife((a: number, b: number) => a + b, 1, 2)).toBe(3)
+  expect(functionIife(() => "ok")).toBe("ok")
+})
+
+test("functionOnce only executes once", () => {
+  let calls = 0
+  const onceFn = functionOnce((value: number) => {
+    calls = calls + 1
+    return value * 2
+  })
+
+  expect(onceFn(5)).toBe(10)
+  expect(onceFn(10)).toBe(10)
+  expect(calls).toBe(1)
+
+  let times = 0
+  const onceWithSubscriber = functionOnce((value: number) => value * 2, (count) => { times = count })
+  onceWithSubscriber(5)
+  onceWithSubscriber(10)
+  expect(times).toBe(2)
+})
+
+test("functionDebounceSimple delays execution", () => {
+  vi.useFakeTimers()
+  try {
+    const spy = vi.fn()
+    const debounced = functionDebounceSimple(spy, 100)
+
+    debounced(5)
+    debounced(10)
+    expect(spy).not.toHaveBeenCalled()
+
+    vi.advanceTimersByTime(100)
+    expect(spy).toHaveBeenCalledTimes(1)
+    expect(spy).toHaveBeenCalledWith(10)
+  }
+  finally {
+    vi.useRealTimers()
+  }
+})
+
+test("debounce resolves all calls with the last result", async () => {
+  vi.useFakeTimers()
+  try {
+    const debounced = debounce((value: number) => value * 2, 100)
+    const result1 = debounced(5)
+    const result2 = debounced(10)
+
+    vi.advanceTimersByTime(100)
+    await expect(Promise.all([result1, result2])).resolves.toEqual([20, 20])
+  }
+  finally {
+    vi.useRealTimers()
+  }
+})
+
+test("functionThrottleTimeSimple limits calls by time", () => {
+  vi.useFakeTimers()
+  try {
+    const spy = vi.fn()
+    const throttled = functionThrottleTimeSimple(spy, 100)
+
+    throttled(1)
+    throttled(2)
+    expect(spy).toHaveBeenCalledTimes(1)
+
+    vi.advanceTimersByTime(100)
+    throttled(3)
+    expect(spy).toHaveBeenCalledTimes(2)
+  }
+  finally {
+    vi.useRealTimers()
+  }
+})
+
+test("functionThrottleSimple coalesces async calls", async () => {
+  let calls = 0
+  // oxlint-disable-next-line require-await
+  const throttled = functionThrottleSimple(async () => {
+    calls = calls + 1
+  })
+
+  throttled()
+  throttled()
+  await Promise.resolve()
+  expect(calls).toBe(1)
+
+  throttled()
+  await Promise.resolve()
+  expect(calls).toBe(2)
+})
+
+test("throttleTime resolves concurrent calls with one execution", async () => {
+  vi.useFakeTimers()
+  try {
+    const spy = vi.fn((value: number) => value * 2)
+    const throttled = throttleTime(spy, 100)
+
+    const result1 = throttled(2)
+    const result2 = throttled(3)
+
+    await expect(Promise.all([result1, result2])).resolves.toEqual([4, 4])
+    expect(spy).toHaveBeenCalledTimes(1)
+
+    vi.advanceTimersByTime(100)
+    const result3 = throttled(4)
+    await expect(result3).resolves.toBe(8)
+    expect(spy).toHaveBeenCalledTimes(2)
+  }
+  finally {
+    vi.useRealTimers()
+  }
+})
+
+test("functionThrottle coalesces concurrent calls", async () => {
+  let calls = 0
+  const throttled = functionThrottle(() => {
+    calls = calls + 1
+    return "ok"
+  })
+
+  const result1 = throttled()
+  const result2 = throttled()
+
+  await expect(Promise.all([result1, result2])).resolves.toEqual(["ok", "ok"])
+  expect(calls).toBe(1)
+})
+
+test("functionCompose applies right-to-left", () => {
+  const addOne = (value: number): number => value + 1
+  const double = (value: number): number => value * 2
+  const composed = functionCompose(addOne, double)
+
+  expect(composed(2)).toBe(5)
+  expect(functionCompose()(3)).toBe(3)
+})
+
+test("functionPipe applies left-to-right", () => {
+  const addOne = (value: number): number => value + 1
+  const double = (value: number): number => value * 2
+  const piped = functionPipe(addOne, double)
+
+  expect(piped(2)).toBe(6)
+  expect(functionPipe()(3)).toBe(3)
+})
+
+test("functionMemorize caches results", () => {
+  let calls = 0
+  const sum = (a: number, b: number): number => {
+    calls = calls + 1
+    return a + b
+  }
+  const memoized = functionMemorize(sum)
+
+  expect(memoized(1, 2)).toBe(3)
+  expect(memoized(1, 2)).toBe(3)
+  expect(calls).toBe(1)
+})

package/tests/unit/basic/helper.spec.ts

@@ -0,0 +1,118 @@
+import { expect, test } from "vitest"
+
+import {
+  asIs,
+  asNull,
+  asUndefined,
+  asVoid,
+  cases,
+  guards,
+  ifElse,
+  iif,
+  isLooseEqual,
+  isObjectEqual,
+  isStrictEqual,
+  tryCatch,
+  unless,
+  when,
+} from "#Source/basic/index.ts"
+
+test("asIs returns the input unchanged", () => {
+  expect(asIs(5)).toBe(5)
+  expect(asIs("hello", 1, 2, 3)).toBe("hello")
+})
+
+test("asUndefined always returns undefined", () => {
+  expect(asUndefined()).toBeUndefined()
+  expect(asUndefined(1, "hello", null)).toBeUndefined()
+})
+
+test("asNull always returns null", () => {
+  expect(asNull()).toBeNull()
+  expect(asNull(1, "hello", undefined)).toBeNull()
+})
+
+test("asVoid always returns undefined", () => {
+  expect(asVoid()).toBeUndefined()
+  expect(asVoid(1, "hello", null)).toBeUndefined()
+})
+
+test("isStrictEqual compares with ===", () => {
+  expect(isStrictEqual(1, 1)).toBe(true)
+  expect(isStrictEqual(1, "1")).toBe(false)
+})
+
+test("isLooseEqual compares with ==", () => {
+  expect(isLooseEqual(1, "1")).toBe(true)
+  expect(isLooseEqual(0, "1")).toBe(false)
+})
+
+test("isObjectEqual compares with Object.is", () => {
+  expect(isObjectEqual(Number.NaN, Number.NaN)).toBe(true)
+  expect(isObjectEqual(0, -0)).toBe(false)
+})
+
+test("ifElse chooses branch based on predicate", () => {
+  const yes = (): string => "yes"
+  const no = (): string => "no"
+
+  expect(ifElse(true, yes, no)).toBe("yes")
+  expect(ifElse(false, yes, no)).toBe("no")
+  expect(ifElse((value?: number) => (value ?? 0) > 3, yes, no, 4)).toBe("yes")
+})
+
+test("when invokes whenFn only for truthy predicate", () => {
+  const plusOne = (value?: number): number => (value ?? 0) + 1
+
+  expect(when(true, plusOne, 3)).toBe(4)
+  expect(when(false, plusOne, 3)).toBe(3)
+  expect(when((value?: number) => (value ?? 0) > 1, plusOne, 2)).toBe(3)
+})
+
+test("unless invokes unlessFn only for falsy predicate", () => {
+  const plusOne = (value?: number): number => (value ?? 0) + 1
+
+  expect(unless(false, plusOne, 1)).toBe(2)
+  expect(unless(true, plusOne, 1)).toBe(1)
+  expect(unless((value?: number) => (value ?? 0) > 1, plusOne, 0)).toBe(1)
+})
+
+test("iif returns immediate values based on condition", () => {
+  expect(iif(true, "yes", "no")).toBe("yes")
+  expect(iif(false, "yes", "no")).toBe("no")
+  expect(iif((value?: string) => value === "ok", "ok", "no")).toBe("ok")
+})
+
+test("guards returns the first matching guard", () => {
+  expect(
+    guards(
+      [
+        [false, "a"],
+        [true, "b"],
+      ],
+      "z",
+    ),
+  ).toBe("b")
+  expect(guards([[false, "a"]], "z")).toBe("z")
+})
+
+test("cases returns the first predicate match", () => {
+  expect(
+    cases(
+      3,
+      [
+        [(value?: number): boolean => (value ?? 0) > 5, "big"],
+        [(value?: number): boolean => (value ?? 0) > 1, "mid"],
+      ],
+      "small",
+    ),
+  ).toBe("mid")
+  expect(cases(0, [[(value?: number): boolean => (value ?? 0) > 1, "mid"]], "small")).toBe("small")
+})
+
+test("tryCatch returns catch value or undefined", () => {
+  expect(tryCatch(() => "ok", () => "error")).toBe("ok")
+  expect(tryCatch(() => { throw new Error("fail") }, () => "error")).toBe("error")
+  expect(tryCatch(() => { throw new Error("fail") }, 0)).toBe(0)
+  expect(tryCatch(() => { throw new Error("fail") })).toBeUndefined()
+})

package/tests/unit/basic/number.spec.ts

@@ -0,0 +1,74 @@
+import { expect, test } from "vitest"
+
+import {
+  between,
+  constrainNumber,
+  isEven,
+  isOdd,
+  maxOf,
+  maxTo,
+  minOf,
+  minTo,
+  normalize,
+  randomBetween,
+  randomIntBetween,
+} from "#Source/basic/index.ts"
+
+test("normalize scales values to 0-1 and validates ranges", () => {
+  expect(normalize(5, 0, 10)).toBe(0.5)
+  expect(normalize(2, 2, 6)).toBe(0)
+  expect(() => normalize(1, 2, 2)).toThrow("Min and max value are the same.")
+  expect(() => normalize(12, 0, 10)).toThrow("Value 12 is not in the range of 0 to 10.")
+})
+
+test("isEven returns expected values", () => {
+  expect(isEven(10)).toBe(true)
+  expect(isEven(7)).toBe(false)
+})
+
+test("isOdd returns expected values", () => {
+  expect(isOdd(7)).toBe(true)
+  expect(isOdd(10)).toBe(false)
+})
+
+test("maxTo clamps values", () => {
+  expect(maxTo(5, 10)).toBe(5)
+  expect(maxTo(5, 3)).toBe(3)
+})
+
+test("minTo clamps values", () => {
+  expect(minTo(5, 3)).toBe(5)
+  expect(minTo(5, 8)).toBe(8)
+})
+
+test("minOf returns expected values", () => {
+  expect(minOf(2, 9)).toBe(2)
+  expect(minOf(5, -1)).toBe(-1)
+})
+
+test("maxOf returns expected values", () => {
+  expect(maxOf(2, 9)).toBe(9)
+  expect(maxOf(5, -1)).toBe(5)
+})
+
+test("between clamps to provided bounds", () => {
+  expect(between(0, 10, 5)).toBe(5)
+  expect(between(0, 10, -3)).toBe(0)
+  expect(between(10, 0, 12)).toBe(10)
+})
+
+test("randomBetween returns inclusive values", () => {
+  expect(randomBetween(4, 4)).toBe(4)
+  expect(randomBetween(10, 10)).toBe(10)
+})
+
+test("randomIntBetween returns inclusive values regardless of order", () => {
+  expect(randomIntBetween(4, 4)).toBe(4)
+  expect(randomIntBetween(10, 10)).toBe(10)
+})
+
+test("constrainNumber applies step and bounds", () => {
+  expect(constrainNumber(12, { step: 5, max: 10 })).toBe(10)
+  expect(constrainNumber(2.6, { step: 0.5, min: 3 })).toBe(3)
+  expect(constrainNumber(7, { min: 2, max: 9 })).toBe(7)
+})

package/tests/unit/basic/object.spec.ts

@@ -0,0 +1,15 @@
+import { expect, test } from "vitest"
+
+import { excludeFields, includeFields } from "#Source/basic/object.ts"
+
+test("includeFields picks specified keys", () => {
+  expect(includeFields({ a: 1, b: 2, c: 3 }, ["a", "c"])).toEqual({ a: 1, c: 3 })
+  // @ts-expect-error - Testing behavior with null input
+  expect(includeFields(null, ["a"])).toEqual({})
+})
+
+test("excludeFields omits specified keys", () => {
+  expect(excludeFields({ a: 1, b: 2 }, ["b"])).toEqual({ a: 1 })
+  // @ts-expect-error - Testing behavior with undefined input
+  expect(excludeFields(undefined, ["a"])).toEqual({})
+})

package/tests/unit/basic/promise.spec.ts

@@ -0,0 +1,232 @@
+// oxlint-disable require-await
+import { expect, test, vi } from "vitest"
+
+import {
+  isPromiseFailResult,
+  promiseCatch,
+  promiseConstructFailResult,
+  promiseFilterFailResults,
+  promiseFilterSuccessResults,
+  promiseFinally,
+  promiseForever,
+  promiseInterval,
+  promiseQueue,
+  promiseRetryUntil,
+  promiseRetryWhile,
+  promiseThen,
+} from "#Source/basic/index.ts"
+
+test("promiseThen chains and transforms resolved values", async () => {
+  const example1 = await promiseThen((value: number) => value * 2, Promise.resolve(3))
+  const example2 = await promiseThen((value: string) => `${value}!`, Promise.resolve("ok"))
+
+  expect(example1).toBe(6)
+  expect(example2).toBe("ok!")
+})
+
+test("promiseCatch handles rejected and resolved promises", async () => {
+  const example1 = await promiseCatch(() => "fallback", Promise.reject(new Error("x")))
+  const example2 = await promiseCatch(() => 0, Promise.resolve(3))
+
+  expect(example1).toBe("fallback")
+  expect(example2).toBe(3)
+})
+
+test("promiseFinally runs finalizer and preserves resolution", async () => {
+  let cleaned = false
+
+  const example1 = await promiseFinally(() => {
+    cleaned = true
+  }, Promise.resolve(10))
+
+  expect(example1).toBe(10)
+  expect(cleaned).toBe(true)
+})
+
+test("promiseConstructFailResult creates standardized failure objects", () => {
+  const reason = new Error("x")
+  const failResult = promiseConstructFailResult(reason)
+
+  expect(isPromiseFailResult(failResult)).toBe(true)
+  expect(failResult.reason).toBe(reason)
+})
+
+test("isPromiseFailResult identifies standardized failure objects", () => {
+  const failResult = promiseConstructFailResult(new Error("x"))
+
+  expect(isPromiseFailResult(failResult)).toBe(true)
+  expect(isPromiseFailResult({ reason: "x" })).toBe(false)
+  expect(isPromiseFailResult(null)).toBe(false)
+})
+
+test("promiseFilterSuccessResults keeps only successful values", () => {
+  const failResult = promiseConstructFailResult(new Error("x"))
+
+  const filtered = promiseFilterSuccessResults([1, failResult, 2])
+
+  expect(filtered).toEqual([1, 2])
+})
+
+test("promiseFilterFailResults keeps failure values with original indices", async () => {
+  const results = await promiseQueue<number>([
+    async (): Promise<number> => 1,
+    async () => {
+      throw new Error("a")
+    },
+    async () => {
+      throw new Error("b")
+    },
+  ])
+
+  const filtered = promiseFilterFailResults(results)
+
+  expect(filtered).toHaveLength(2)
+  expect(filtered[0]?.index).toBe(1)
+  expect(filtered[1]?.index).toBe(2)
+  expect(isPromiseFailResult(filtered[0])).toBe(true)
+  expect(isPromiseFailResult(filtered[1])).toBe(true)
+})
+
+test("promiseQueue executes makers in sequence and keeps failed results", async () => {
+  const results = await promiseQueue<number>([
+    async (): Promise<number> => 1,
+    async ({ previousResult, index }): Promise<number> => {
+      return isPromiseFailResult(previousResult) ? -1 : previousResult + index + 1
+    },
+    async ({ previousResult }): Promise<number> => {
+      if (isPromiseFailResult(previousResult)) {
+        return -1
+      }
+      throw new Error(String(previousResult))
+    },
+    async ({ previousResult }): Promise<number> => {
+      return isPromiseFailResult(previousResult) ? -1 : previousResult + 1
+    },
+  ])
+
+  expect(results[0]).toBe(1)
+  expect(results[1]).toBe(3)
+  expect(isPromiseFailResult(results[2])).toBe(true)
+  expect(results[3]).toBe(-1)
+})
+
+test("promiseRetryWhile retries while predicate is true", async () => {
+  let attempts = 0
+
+  const success = await promiseRetryWhile(
+    (value) => value < 3,
+    async () => {
+      attempts = attempts + 1
+      return attempts
+    },
+    { maxTryTimes: 5 },
+  )
+
+  attempts = 0
+  const failed = await promiseRetryWhile(
+    () => true,
+    async () => {
+      attempts = attempts + 1
+      throw new Error("x")
+    },
+    { maxTryTimes: 2 },
+  )
+
+  await expect(promiseRetryWhile(async () => false, async () => 1, { maxTryTimes: 0 })).rejects.toThrow(
+    "`maxTryTimes` must be greater than 0.",
+  )
+
+  expect(success).toBe(3)
+  expect(attempts).toBe(2)
+  expect(isPromiseFailResult(failed)).toBe(true)
+})
+
+test("promiseRetryUntil retries until predicate becomes true", async () => {
+  let attempts = 0
+
+  const success = await promiseRetryUntil(
+    (value, time) => value >= 2 && time >= 2,
+    async () => {
+      attempts = attempts + 1
+      return attempts
+    },
+    { maxTryTimes: 5 },
+  )
+
+  attempts = 0
+  const failed = await promiseRetryUntil(
+    () => false,
+    async () => {
+      attempts = attempts + 1
+      throw new Error("x")
+    },
+    { maxTryTimes: 2 },
+  )
+
+  await expect(promiseRetryUntil(async () => true, async () => 1, { maxTryTimes: 0 })).rejects.toThrow(
+    "`maxTryTimes` must be greater than 0.",
+  )
+
+  expect(success).toBe(2)
+  expect(attempts).toBe(2)
+  expect(isPromiseFailResult(failed)).toBe(true)
+})
+
+test("promiseInterval runs by interval and returns a stopper", async () => {
+  vi.useFakeTimers()
+
+  try {
+    const calls: number[] = []
+    const stop = promiseInterval(10, async (time) => {
+      calls.push(time)
+      return time
+    })
+
+    vi.advanceTimersByTime(35)
+    await Promise.resolve()
+
+    stop()
+    vi.advanceTimersByTime(50)
+
+    expect(calls).toEqual([1, 2, 3])
+    expect(typeof stop).toBe("function")
+  }
+  finally {
+    vi.useRealTimers()
+  }
+})
+
+test("promiseForever loops continuously and reports rejections", async () => {
+  vi.useFakeTimers()
+
+  try {
+    let value = 0
+    const onRejected = vi.fn()
+    const promiseMaker = vi.fn(async () => {
+      value = value + 1
+      if (value === 1) {
+        throw new Error("first")
+      }
+      return value
+    })
+
+    promiseForever(promiseMaker, { breakTime: 5, onRejected })
+    await Promise.resolve()
+    await Promise.resolve()
+
+    expect(promiseMaker).toHaveBeenCalledTimes(1)
+    expect(onRejected).toHaveBeenCalledTimes(1)
+    expect(onRejected.mock.calls[0]?.[0]).toBe(1)
+    expect(isPromiseFailResult(onRejected.mock.calls[0]?.[1])).toBe(true)
+
+    vi.advanceTimersByTime(16)
+    await Promise.resolve()
+    await Promise.resolve()
+
+    expect(promiseMaker.mock.calls.length).toBeGreaterThanOrEqual(2)
+  }
+  finally {
+    vi.clearAllTimers()
+    vi.useRealTimers()
+  }
+})

package/tests/unit/basic/regexp.spec.ts

@@ -0,0 +1,11 @@
+import { expect, test } from "vitest"
+
+import { regexpIsEmail } from "#Source/basic/index.ts"
+
+test("regexpIsEmail validates email format", () => {
+  expect(regexpIsEmail("user@example.com")).toBe(true)
+  expect(regexpIsEmail("first.last+tag@example.co")).toBe(true)
+  expect(regexpIsEmail("user@localhost")).toBe(false)
+  expect(regexpIsEmail("user@example")).toBe(false)
+  expect(regexpIsEmail("user@.com")).toBe(false)
+})