@planet-matrix/mobius-model 0.3.0 → 0.5.0

package/src/type/union.ts

@@ -0,0 +1,108 @@
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Strict version of builtin `Extract`, `U` must be subset of `T`.
+ */
+export type StrictExtract<T, U extends T> = Extract<T, U>
+/**
+ * Strict version of builtin `Exclude`, `U` must be subset of `T`.
+ */
+export type StrictExclude<T, U extends T> = Exclude<T, U>
+
+// ============================================================================
+// Manipulation
+// ============================================================================
+
+/**
+ * @example
+ * ```
+ * // Expect: "2" | "3"
+ * UnionIntersection<'1' | '2' | '3', '2' | '3' | '4'>;
+ *
+ * // Expect: () => void
+ * UnionIntersection<string | number | (() => void), Function>;
+ * ```
+ */
+export type UnionIntersection<UnionA, UnionB> = UnionA extends UnionB ? UnionA : never
+
+/**
+ * @example
+ * ```
+ * // Expect: "1"
+ * UnionDifference<'1' | '2' | '3', '2' | '3' | '4'>;
+ *
+ * // Expect: string | number
+ * UnionDifference<string | number | (() => void), Function>;
+ * ```
+ */
+export type UnionDifference<UnionA, UnionB> = UnionA extends UnionB ? never : UnionA
+
+/**
+ * @example
+ * ```
+ * // Expect: "1"
+ * UnionComplement<'1' | '2' | '3', '2' | '3'>;
+ * ```
+ */
+export type UnionComplement<Union, SubUnion extends Union> = UnionDifference<Union, SubUnion>
+
+/**
+ * @example
+ * ```
+ * // Expect: "1" | "4"
+ * UnionSymmetricDifference<'1' | '2' | '3', '2' | '3' | '4'>;
+ * ```
+ */
+export type UnionSymmetricDifference<UnionA, UnionB> = UnionDifference<UnionA | UnionB, UnionA & UnionB>
+
+/**
+ * @example
+ * ```
+ * // Expect: "c"
+ * type Result = LastOfUnion<'a' | 'b' | 'c'>
+ * ```
+ */
+export type LastOfUnion<Union> = UnionToIntersection<
+  Union extends unknown ? (x: Union) => void : never
+> extends (x: infer L) => void ? L : never
+
+/**
+ * @example
+ * ```
+ * // Expect: "a" | "b"
+ * type Result = UnionPop<'a' | 'b' | 'c'>
+ * ```
+ */
+export type UnionPop<U> = Exclude<U, LastOfUnion<U>>
+
+// ============================================================================
+// Conversion
+// ============================================================================
+
+/**
+ * @example
+ * ```
+ * // Expect: { name: string } & { age: number } & { visible: boolean }
+ * UnionToIntersection<{ name: string } | { age: number } | { visible: boolean }>
+ * ```
+ * @see {@link https://stackoverflow.com/a/50375286/7381355}
+ */
+export type UnionToIntersection<Union> = (Union extends unknown
+  ? (_: Union) => void
+  : never
+) extends (_: infer Result) => void ? Result : never
+
+type InternalUnionToTuple<U, T extends unknown[]> =
+  [U] extends [never]
+  ? T
+  : InternalUnionToTuple<Exclude<U, LastOfUnion<U>>, [LastOfUnion<U>, ...T]>
+/**
+ * @example
+ * ```
+ * // Expect: ["1", "2", "3"]
+ * type Example = UnionToTuple<'1' | '2' | '3'>
+ * ```
+ */
+export type UnionToTuple<U> = InternalUnionToTuple<U, []>

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

@@ -0,0 +1,290 @@
+import { expect, test } from "vitest"
+
+import {
+  arrayAdjust,
+  arrayAll,
+  arrayAny,
+  arrayAppend,
+  arrayConcat,
+  arrayDrop,
+  arrayDropLast,
+  arrayEvery,
+  arrayFilter,
+  arrayFlat,
+  arrayFlatMap,
+  arrayForEach,
+  arrayFromSpread,
+  arrayHead,
+  arrayIncludes,
+  arrayIndexOf,
+  arrayInit,
+  arrayIntersection,
+  arrayJoin,
+  arrayLast,
+  arrayLastIndexOf,
+  arrayLength,
+  arrayMap,
+  arrayPartition,
+  arrayPop,
+  arrayPrepend,
+  arrayPush,
+  arrayReduce,
+  arrayReduceLeft,
+  arrayReduceRight,
+  arrayReject,
+  arrayRemove,
+  arrayRemoveIndex,
+  arrayReverse,
+  arrayShift,
+  arraySlice,
+  arraySliceInit,
+  arraySliceTail,
+  arraySome,
+  arraySort,
+  arrayTail,
+  arrayUnion,
+  arrayUnique,
+  arrayUniqueBy,
+  arrayUnshift,
+  arrayUpdate,
+  shuffle,
+} from "#Source/basic/index.ts"
+
+test("arrayFromSpread converts iterables", () => {
+  expect(arrayFromSpread(new Set([1, 2, 3]))).toEqual([1, 2, 3])
+  expect(arrayFromSpread([])).toEqual([])
+})
+
+test("arrayLength returns array length", () => {
+  expect(arrayLength(["a", "b", "c"])).toBe(3)
+  expect(arrayLength([])).toBe(0)
+})
+
+test("arrayPop removes the last item", () => {
+  expect(arrayPop([1, 2, 3])).toEqual([1, 2])
+  expect(arrayPop(["only"])).toEqual([])
+})
+
+test("arrayPush appends an item", () => {
+  expect(arrayPush(3, [1, 2])).toEqual([1, 2, 3])
+  expect(arrayPush("a", [])).toEqual(["a"])
+})
+
+test("arrayAppend aliases arrayPush", () => {
+  expect(arrayAppend(2, [1])).toEqual([1, 2])
+  expect(arrayAppend("x", [])).toEqual(["x"])
+})
+
+test("arrayUnshift prepends an item", () => {
+  expect(arrayUnshift(0, [1, 2])).toEqual([0, 1, 2])
+  expect(arrayUnshift("a", [])).toEqual(["a"])
+})
+
+test("arrayPrepend aliases arrayUnshift", () => {
+  expect(arrayPrepend("first", ["second"])).toEqual(["first", "second"])
+  expect(arrayPrepend(true, [])).toEqual([true])
+})
+
+test("arrayShift removes the first item", () => {
+  expect(arrayShift([1, 2, 3])).toEqual([2, 3])
+  expect(arrayShift(["only"])).toEqual([])
+})
+
+test("arrayHead returns the first element", () => {
+  expect(arrayHead([1, 2, 3])).toBe(1)
+  expect(arrayHead([])).toBeUndefined()
+})
+
+test("arrayTail returns all but the first element", () => {
+  expect(arrayTail([1, 2, 3])).toEqual([2, 3])
+  expect(arrayTail(["only"])).toEqual([])
+})
+
+test("arrayInit returns all but the last element", () => {
+  expect(arrayInit([1, 2, 3])).toEqual([1, 2])
+  expect(arrayInit(["only"])).toEqual([])
+})
+
+test("arrayLast returns the last element", () => {
+  expect(arrayLast([1, 2, 3])).toBe(3)
+  expect(arrayLast([])).toBeUndefined()
+})
+
+test("arraySlice returns a portion of the array", () => {
+  expect(arraySlice(1, 3, ["a", "b", "c", "d"])).toEqual(["b", "c"])
+  expect(arraySlice(2, 2, [1, 2, 3])).toEqual([])
+})
+
+test("arraySliceTail returns a tail slice", () => {
+  expect(arraySliceTail(2, [1, 2, 3, 4])).toEqual([3, 4])
+  expect(arraySliceTail(1, ["only"])).toEqual([])
+})
+
+test("arrayDrop drops a rounded count", () => {
+  expect(arrayDrop(2, [1, 2, 3, 4])).toEqual([3, 4])
+  expect(arrayDrop(-2, [1, 2])).toEqual([])
+})
+
+test("arraySliceInit returns a head slice", () => {
+  expect(arraySliceInit(2, [1, 2, 3, 4])).toEqual([1, 2])
+  expect(arraySliceInit(0, [1, 2])).toEqual([])
+})
+
+test("arrayDropLast drops elements from the end", () => {
+  expect(arrayDropLast(2, [1, 2, 3, 4])).toEqual([1, 2])
+  expect(arrayDropLast(3, [1, 2])).toEqual([])
+})
+
+test("arrayRemove removes a range", () => {
+  expect(arrayRemove(1, 3, ["a", "b", "c", "d"])).toEqual(["a", "d"])
+  expect(arrayRemove(3, 1, [1, 2, 3, 4])).toEqual([1, 4])
+})
+
+test("arrayRemoveIndex removes a single index", () => {
+  expect(arrayRemoveIndex(1, ["a", "b", "c"])).toEqual(["a", "c"])
+  expect(arrayRemoveIndex(0, ["only"])).toEqual([])
+})
+
+test("arrayConcat appends arrays", () => {
+  expect(arrayConcat([3, 4], [1, 2])).toEqual([1, 2, 3, 4])
+  expect(arrayConcat([], ["a"])).toEqual(["a"])
+})
+
+test("arrayJoin joins elements", () => {
+  expect(arrayJoin(",", ["a", "b", "c"])).toBe("a,b,c")
+  expect(arrayJoin("-", [])).toBe("")
+})
+
+test("arrayIndexOf finds the first index", () => {
+  expect(arrayIndexOf("b", ["a", "b", "c"])).toBe(1)
+  expect(arrayIndexOf(9, [1, 2, 3])).toBe(-1)
+})
+
+test("arrayLastIndexOf finds the last index", () => {
+  expect(arrayLastIndexOf("a", ["a", "b", "a"])).toBe(2)
+  expect(arrayLastIndexOf(9, [1, 2, 3])).toBe(-1)
+})
+
+test("arrayIncludes checks membership", () => {
+  expect(arrayIncludes(2, [1, 2, 3])).toBe(true)
+  expect(arrayIncludes("x", ["a", "b"])).toBe(false)
+})
+
+test("arrayEvery verifies all items", () => {
+  expect(arrayEvery((item) => item > 0, [1, 2, 3])).toBe(true)
+  expect(arrayEvery((item) => item > 1, [1, 2, 3])).toBe(false)
+})
+
+test("arrayAll aliases arrayEvery", () => {
+  expect(arrayAll((item) => item !== null, [1, 2])).toBe(true)
+  expect(arrayAll((item) => item === 0, [0, 1])).toBe(false)
+})
+
+test("arraySome verifies at least one item", () => {
+  expect(arraySome((item) => item > 2, [1, 2, 3])).toBe(true)
+  expect(arraySome((item) => item < 0, [1, 2, 3])).toBe(false)
+})
+
+test("arrayAny aliases arraySome", () => {
+  expect(arrayAny((item) => item === "b", ["a", "b"])).toBe(true)
+  expect(arrayAny((item) => item === "x", ["a", "b"])).toBe(false)
+})
+
+test("arrayForEach applies the callback", () => {
+  const target: number[] = []
+  arrayForEach((item) => target.push(item * 2), [1, 2, 3])
+  expect(target).toEqual([2, 4, 6])
+})
+
+test("arrayFilter keeps matching elements", () => {
+  expect(arrayFilter((item) => item % 2 === 0, [1, 2, 3, 4])).toEqual([2, 4])
+  expect(arrayFilter((item) => item > 0, [])).toEqual([])
+})
+
+test("arrayReject removes matching elements", () => {
+  expect(arrayReject((item) => item % 2 === 0, [1, 2, 3, 4])).toEqual([1, 3])
+  expect(arrayReject((item) => item === "b", ["a", "b"])).toEqual(["a"])
+})
+
+test("arrayPartition splits by predicate", () => {
+  expect(arrayPartition((item) => item % 2 === 0, [1, 2, 3, 4])).toEqual([[2, 4], [1, 3]])
+  expect(arrayPartition((item) => item === "b", ["a"])).toEqual([[], ["a"]])
+})
+
+test("arrayMap transforms values", () => {
+  expect(arrayMap((item) => item * 2, [1, 2, 3])).toEqual([2, 4, 6])
+  expect(arrayMap((item) => item, [])).toEqual([])
+})
+
+test("arrayFlat flattens to specified depth", () => {
+  expect(arrayFlat(1, [1, [2, 3], [4]])).toEqual([1, 2, 3, 4])
+  expect(arrayFlat(2, [1, [[2]]])).toEqual([1, 2])
+})
+
+test("arrayFlatMap maps and flattens", () => {
+  expect(arrayFlatMap((item) => [item, item], [1, 2])).toEqual([1, 1, 2, 2])
+  expect(arrayFlatMap((item) => [item], [])).toEqual([])
+})
+
+test("arrayReduce aggregates left to right", () => {
+  expect(arrayReduce((acc, item) => acc + item, 0, [1, 2, 3])).toBe(6)
+  expect(arrayReduce((acc, item) => acc + item, "", ["a", "b", "c"])).toBe("abc")
+})
+
+test("arrayReduceLeft aliases arrayReduce", () => {
+  expect(arrayReduceLeft((acc, item) => acc + item, 0, [1, 2, 3])).toBe(6)
+  expect(arrayReduceLeft((acc, item) => acc + item, "", ["a", "b"])).toBe("ab")
+})
+
+test("arrayReduceRight aggregates right to left", () => {
+  expect(arrayReduceRight((acc, item) => acc + item, "", ["a", "b", "c"])).toBe("cba")
+  expect(arrayReduceRight((acc, item) => acc + item, 0, [1, 2, 3])).toBe(6)
+})
+
+test("arrayUnique removes duplicates", () => {
+  expect(arrayUnique([1, 2, 1, 3])).toEqual([1, 2, 3])
+  expect(arrayUnique(["a", "a"])).toEqual(["a"])
+})
+
+test("arrayUniqueBy removes duplicates by key", () => {
+  const input = [{ id: 1 }, { id: 1 }, { id: 2 }]
+  expect(arrayUniqueBy((item) => item.id, input)).toEqual([{ id: 1 }, { id: 2 }])
+  expect(arrayUniqueBy((item) => item, [])).toEqual([])
+})
+
+test("arrayUnion combines unique values", () => {
+  expect(arrayUnion([1, 2], [2, 3])).toEqual([1, 2, 3])
+  expect(arrayUnion(["a"], [])).toEqual(["a"])
+})
+
+test("arrayIntersection finds common values", () => {
+  expect(arrayIntersection([1, 2], [2, 3])).toEqual([2])
+  expect(arrayIntersection(["a"], ["b"])).toEqual([])
+})
+
+test("arrayReverse returns reversed copy", () => {
+  expect(arrayReverse([1, 2, 3])).toEqual([3, 2, 1])
+  expect(arrayReverse([])).toEqual([])
+})
+
+test("arraySort sorts with compare function", () => {
+  expect(arraySort((a, b) => a - b, [3, 1, 2])).toEqual([1, 2, 3])
+  expect(arraySort((a, b) => a.localeCompare(b), ["b", "a"])).toEqual(["a", "b"])
+})
+
+test("shuffle preserves elements", () => {
+  const input = [1, 2, 3, 4]
+  const result = shuffle(input)
+  expect(result).toHaveLength(4)
+  expect(result.toSorted((a, b) => a - b)).toEqual(input.toSorted((a, b) => a - b))
+})
+
+test("arrayAdjust replaces a value via callback", () => {
+  expect(arrayAdjust(1, (item) => item * 10, [1, 2, 3])).toEqual([1, 20, 3])
+  expect(arrayAdjust(0, (item) => item, ["a"])).toEqual(["a"])
+})
+
+test("arrayUpdate replaces a value", () => {
+  expect(arrayUpdate(1, 9, [1, 2, 3])).toEqual([1, 9, 3])
+  expect(arrayUpdate(0, "x", ["a"])).toEqual(["x"])
+})

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

@@ -0,0 +1,50 @@
+import { expect, test } from "vitest"
+
+import {
+  bigintAbs,
+  bigintClamp,
+  bigintIsNegative,
+  bigintIsPositive,
+  bigintIsZero,
+  bigintMaxOf,
+  bigintMinOf,
+} from "#Source/basic/index.ts"
+
+test("bigintIsZero returns expected values", () => {
+  expect(bigintIsZero(0n)).toBe(true)
+  expect(bigintIsZero(2n)).toBe(false)
+  expect(bigintIsZero(0)).toBe(false)
+})
+
+test("bigintIsPositive returns expected values", () => {
+  expect(bigintIsPositive(3n)).toBe(true)
+  expect(bigintIsPositive(0n)).toBe(false)
+  expect(bigintIsPositive(-1n)).toBe(false)
+})
+
+test("bigintIsNegative returns expected values", () => {
+  expect(bigintIsNegative(-3n)).toBe(true)
+  expect(bigintIsNegative(0n)).toBe(false)
+  expect(bigintIsNegative(1n)).toBe(false)
+})
+
+test("bigintAbs returns absolute values", () => {
+  expect(bigintAbs(-5n)).toBe(5n)
+  expect(bigintAbs(2n)).toBe(2n)
+})
+
+test("bigintMinOf returns expected values", () => {
+  expect(bigintMinOf(2n, 9n)).toBe(2n)
+  expect(bigintMinOf(5n, -1n)).toBe(-1n)
+})
+
+test("bigintMaxOf returns expected values", () => {
+  expect(bigintMaxOf(2n, 9n)).toBe(9n)
+  expect(bigintMaxOf(5n, -1n)).toBe(5n)
+})
+
+test("bigintClamp clamps to provided bounds", () => {
+  expect(bigintClamp(0n, 10n, 5n)).toBe(5n)
+  expect(bigintClamp(0n, 10n, -3n)).toBe(0n)
+  expect(bigintClamp(10n, 0n, 12n)).toBe(10n)
+})

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

@@ -0,0 +1,74 @@
+import { expect, test } from "vitest"
+
+import {
+  booleanAnd,
+  booleanComplement,
+  booleanFrom,
+  booleanIsFalsy,
+  booleanIsTruthy,
+  booleanNand,
+  booleanNor,
+  booleanNot,
+  booleanOr,
+  booleanXnor,
+  booleanXor,
+} from "#Source/basic/index.ts"
+
+test("boolean converts values", () => {
+  expect(booleanFrom(1)).toBe(true)
+  expect(booleanFrom(0)).toBe(false)
+  expect(booleanFrom("")).toBe(false)
+})
+
+test("booleanNot inverts values", () => {
+  expect(booleanNot(true)).toBe(false)
+  expect(booleanNot(0)).toBe(true)
+})
+
+test("booleanAnd performs logical AND", () => {
+  expect(booleanAnd(true, 1)).toBe(true)
+  expect(booleanAnd(true, 0)).toBe(false)
+})
+
+test("booleanOr performs logical OR", () => {
+  expect(booleanOr(false, "a")).toBe(true)
+  expect(booleanOr(false, 0)).toBe(false)
+})
+
+test("booleanNand performs logical NAND", () => {
+  expect(booleanNand(true, true)).toBe(false)
+  expect(booleanNand(true, 0)).toBe(true)
+})
+
+test("booleanNor performs logical NOR", () => {
+  expect(booleanNor(false, 0)).toBe(true)
+  expect(booleanNor(true, false)).toBe(false)
+})
+
+test("booleanXor performs logical XOR", () => {
+  expect(booleanXor(true, false)).toBe(true)
+  expect(booleanXor(true, 1)).toBe(false)
+})
+
+test("booleanXnor performs logical XNOR", () => {
+  expect(booleanXnor(true, true)).toBe(true)
+  expect(booleanXnor(true, 0)).toBe(false)
+})
+
+test("booleanComplement inverts predicate result", () => {
+  const isEven = (value: number): boolean => value % 2 === 0
+  const isOdd = booleanComplement(isEven)
+
+  expect(isOdd(3)).toBe(true)
+  expect(isOdd(4)).toBe(false)
+})
+
+test("booleanIsTruthy checks truthy values", () => {
+  expect(booleanIsTruthy("ok")).toBe(true)
+  expect(booleanIsTruthy("")).toBe(false)
+})
+
+test("booleanIsFalsy checks falsy values", () => {
+  expect(booleanIsFalsy(0)).toBe(true)
+  expect(booleanIsFalsy("0")).toBe(false)
+})

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

@@ -0,0 +1,32 @@
+import { expect, test } from "vitest"
+
+import {
+  errorIsNetworkError,
+  errorStringifyException,
+} from "#Source/basic/index.ts"
+
+test("errorIsNetworkError returns expected values", () => {
+  expect(errorIsNetworkError(null)).toBe(false)
+  expect(errorIsNetworkError(undefined)).toBe(false)
+  expect(errorIsNetworkError("Network request failed")).toBe(false)
+
+  const nonTypeError = new Error("Failed to fetch")
+  expect(errorIsNetworkError(nonTypeError)).toBe(false)
+
+  const networkError = new TypeError("Failed to fetch")
+  expect(errorIsNetworkError(networkError)).toBe(true)
+
+  const safariError = new TypeError("Load failed")
+  // @ts-expect-error --- IGNORE ---
+  safariError.stack = undefined
+  expect(errorIsNetworkError(safariError)).toBe(true)
+
+  const safariWithStack = new TypeError("Load failed")
+  safariWithStack.stack = "TypeError: Load failed"
+  expect(errorIsNetworkError(safariWithStack)).toBe(false)
+})
+
+test("errorStringifyException returns readable output", () => {
+  expect(errorStringifyException(new Error("boom"))).toBe("Error: boom")
+  expect(errorStringifyException(123)).toBe("123")
+})