@planet-matrix/mobius-model 0.3.0 → 0.4.0

package/src/basic/number.ts

@@ -0,0 +1,178 @@
+/**
+ * Normalize a value to a 0-1 range based on min and max.
+ *
+ * @example
+ * ```
+ * // Expect: 0.5
+ * const example1 = normalize(5, 0, 10)
+ * // Expect: 0
+ * const example2 = normalize(2, 2, 6)
+ * ```
+ */
+export const normalize = (value: number, min: number, max: number): number => {
+  if (min === max) {
+    throw new Error("Min and max value are the same.")
+  }
+  if (value < min || value > max) {
+    throw new Error(`Value ${value} is not in the range of ${min} to ${max}.`)
+  }
+  return (value - min) / (max - min)
+}
+
+/**
+ * Check if a number is even.
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = isEven(10)
+ * // Expect: false
+ * const example2 = isEven(7)
+ * ```
+ */
+export const isEven = (x: number): boolean => x % 2 === 0
+
+/**
+ * Check if a number is odd.
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = isOdd(7)
+ * // Expect: false
+ * const example2 = isOdd(10)
+ * ```
+ */
+export const isOdd = (x: number): boolean => x % 2 !== 0
+
+/**
+ * Clamp a number to a maximum value.
+ *
+ * @example
+ * ```
+ * // Expect: 5
+ * const example1 = maxTo(5, 10)
+ * // Expect: 3
+ * const example2 = maxTo(5, 3)
+ * ```
+ */
+export const maxTo = (max: number, x: number): number => x > max ? max : x
+
+/**
+ * Clamp a number to a minimum value.
+ *
+ * @example
+ * ```
+ * // Expect: 5
+ * const example1 = minTo(5, 3)
+ * // Expect: 8
+ * const example2 = minTo(5, 8)
+ * ```
+ */
+export const minTo = (min: number, x: number): number => x < min ? min : x
+
+/**
+ * Get the smaller of two numbers.
+ *
+ * @example
+ * ```
+ * // Expect: 2
+ * const example1 = minOf(2, 9)
+ * // Expect: -1
+ * const example2 = minOf(5, -1)
+ * ```
+ */
+export const minOf = (x: number, y: number): number => x < y ? x : y
+
+/**
+ * Get the larger of two numbers.
+ *
+ * @example
+ * ```
+ * // Expect: 9
+ * const example1 = maxOf(2, 9)
+ * // Expect: 5
+ * const example2 = maxOf(5, -1)
+ * ```
+ */
+export const maxOf = (x: number, y: number): number => x > y ? x : y
+
+/**
+ * Clamp a number between two bounds.
+ *
+ * @example
+ * ```
+ * // Expect: 5
+ * const example1 = between(0, 10, 5)
+ * // Expect: 0
+ * const example2 = between(0, 10, -3)
+ * ```
+ */
+export const between = (a: number, b: number, x: number): number => {
+  const min = minOf(a, b)
+  const max = maxOf(a, b)
+  return x < min ? min : (x > max ? max : x)
+}
+
+/**
+ * Get a random integer between min and max, inclusive.
+ *
+ * @example
+ * ```
+ * // Expect: 4
+ * const example1 = randomBetween(4, 4)
+ * // Expect: 10
+ * const example2 = randomBetween(10, 10)
+ * ```
+ */
+export const randomBetween = (min: number, max: number): number => {
+  return Math.floor(Math.random() * (max - min + 1) + min)
+}
+
+/**
+ * Get a random integer between two values, regardless of order, inclusive.
+ *
+ * @example
+ * ```
+ * // Expect: 4
+ * const example1 = randomIntBetween(4, 4)
+ * // Expect: 10
+ * const example2 = randomIntBetween(10, 10)
+ * ```
+ */
+export const randomIntBetween = (a: number, b: number): number => {
+  const min = minOf(a, b)
+  const max = maxOf(a, b)
+  return Math.floor(Math.random() * (max - min + 1)) + min
+}
+
+export interface NumberConstraints {
+  min?: number | undefined
+  max?: number | undefined
+  step?: number | undefined
+}
+
+/**
+ * Constrain a number by step size and min/max bounds.
+ *
+ * @example
+ * ```
+ * // Expect: 10
+ * const example1 = constrainNumber(12, { step: 5, max: 10 })
+ * // Expect: 3
+ * const example2 = constrainNumber(2.6, { step: 0.5, min: 3 })
+ * ```
+ */
+export const constrainNumber = (value: number, constraints: NumberConstraints): number => {
+  let constrainedValue = value
+  if (constraints.step !== undefined) {
+    constrainedValue = Math.round(constrainedValue / constraints.step) * constraints.step
+  }
+  if (constraints.min !== undefined) {
+    constrainedValue = Math.max(constraints.min, constrainedValue)
+  }
+  if (constraints.max !== undefined) {
+    constrainedValue = Math.min(constraints.max, constrainedValue)
+  }
+  return constrainedValue
+}

package/src/basic/object.ts

@@ -0,0 +1,58 @@
+import type { AnyRecord } from "../type/index.ts"
+
+/**
+ * Return a new object that includes only the specified keys from the source object.
+ *
+ * @example
+ * ```
+ * // Expect: { a: 1, c: 3 }
+ * const example1 = includeFields({ a: 1, b: 2, c: 3 }, ["a", "c"])
+ * // Expect: {}
+ * const example2 = includeFields(null, ["a"])
+ * ```
+ */
+export const includeFields = <T extends AnyRecord, K extends keyof T>(
+  object: T | null | undefined,
+  keys: K[],
+): Pick<T, K> => {
+  if (object === null || object === undefined) {
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    return {} as Pick<T, K>
+  }
+  const newObject: Partial<Pick<T, K>> = {} // 初始化一个部分类型的对象
+  keys.forEach((key) => {
+    if (key in object) {
+      newObject[key] = object[key]
+    }
+  })
+  // oxlint-disable-next-line no-unsafe-type-assertion
+  return newObject as Pick<T, K> // 使用正确的变量名并断言返回类型
+}
+
+/**
+ * Return a new object that excludes the specified keys from the source object.
+ *
+ * @example
+ * ```
+ * // Expect: { a: 1 }
+ * const example1 = excludeFields({ a: 1, b: 2 }, ["b"])
+ * // Expect: {}
+ * const example2 = excludeFields(undefined, ["a"])
+ * ```
+ */
+export const excludeFields = <T extends AnyRecord, K extends keyof T>(
+  object: T | null | undefined,
+  keys: K[],
+): Omit<T, K> => {
+  if (object === null || object === undefined) {
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    return {} as Omit<T, K>
+  }
+  const newObject: Partial<T> = { ...object } // 创建原对象的浅拷贝
+  keys.forEach((key) => {
+    // oxlint-disable-next-line no-dynamic-delete
+    delete newObject[key] // 删除指定的键
+  })
+  // oxlint-disable-next-line no-unsafe-type-assertion
+  return newObject as Omit<T, K> // 使用Omit类型确保返回的类型反映了被排除的键
+}

package/src/basic/promise.ts

@@ -0,0 +1,464 @@
+import { isPlainObject } from "./is.ts"
+
+/**
+ * Chain a promise with a fulfillment callback and return the transformed result.
+ *
+ * @example
+ * ```
+ * // Expect: 6
+ * const example1 = await promiseThen((value: number) => value * 2, Promise.resolve(3))
+ * // Expect: "ok!"
+ * const example2 = await promiseThen((value: string) => `${value}!`, Promise.resolve("ok"))
+ * ```
+ */
+export const promiseThen = async <V, R>(
+  doSomething: (value: V) => R | PromiseLike<R>,
+  target: Promise<V>,
+): Promise<R> => {
+  return await target.then(doSomething)
+}
+
+/**
+ * Handle a rejected promise and convert it to a resolved fallback value.
+ *
+ * @example
+ * ```
+ * // Expect: "fallback"
+ * const example1 = await promiseCatch(() => "fallback", Promise.reject(new Error("x")))
+ * // Expect: 3
+ * const example2 = await promiseCatch(() => 0, Promise.resolve(3))
+ * ```
+ */
+export const promiseCatch = async <V, R>(
+  doSomething: (reason: unknown) => R | PromiseLike<R>,
+  target: Promise<V>,
+): Promise<V | R> => {
+  return await target.catch(doSomething)
+}
+
+/**
+ * Run a callback after a promise settles and keep the original resolved value.
+ *
+ * @example
+ * ```
+ * let cleaned = false
+ * // Expect: 10
+ * const example1 = await promiseFinally(() => { cleaned = true }, Promise.resolve(10))
+ * // Expect: true
+ * const example2 = cleaned
+ * ```
+ */
+export const promiseFinally = async <V>(
+  doSomething: () => void,
+  target: Promise<V>,
+): Promise<V> => {
+  return await target.finally(doSomething)
+}
+
+const INTERNAL_PROMISE_FAIL_RESULT_TYPE: symbol = Symbol("fail")
+export interface PromiseFailResult {
+  __type__: typeof INTERNAL_PROMISE_FAIL_RESULT_TYPE
+  reason: unknown
+}
+export interface PromiseIndexedFailResult extends PromiseFailResult {
+  index: number
+}
+export const promiseConstructFailResult = (reason: unknown): PromiseFailResult => {
+  return { __type__: INTERNAL_PROMISE_FAIL_RESULT_TYPE, reason }
+}
+/**
+ * Predicate whether the target is a promise fail result.
+ */
+export const isPromiseFailResult = (target: unknown): target is PromiseFailResult => {
+  return isPlainObject(target) && target["__type__"] === INTERNAL_PROMISE_FAIL_RESULT_TYPE
+}
+/**
+ * Designed to use as `onrejected` callback of `Promise.catch`
+ * to return a standard `PromiseFailResult`.
+ */
+export const promiseCatchToFailResult = (reason: unknown): PromiseFailResult => {
+  return { __type__: INTERNAL_PROMISE_FAIL_RESULT_TYPE, reason }
+}
+
+/**
+ * Giving an array, filter non-`PromiseFailResult` items.
+ */
+export const promiseFilterSuccessResults = <V>(
+  results: Array<V | PromiseFailResult>,
+): V[] => {
+  const filtered = results.filter(result => {
+    return isPromiseFailResult(result) === false
+  })
+  // oxlint-disable-next-line no-unsafe-type-assertion
+  return filtered as V[]
+}
+/**
+ * Giving a array, filter `PromiseFailResult` items, with extra `index` property
+ * which indicate the index of the item in the original array.
+ */
+export const promiseFilterFailResults = <V>(
+  results: Array<V | PromiseFailResult>,
+): PromiseIndexedFailResult[] => {
+  const filtered = results.reduce<PromiseIndexedFailResult[]>((
+    accumulatedResults, currentResult, index
+  ) => {
+    if (isPromiseFailResult(currentResult)) {
+      accumulatedResults.push({ ...currentResult, index })
+    }
+    return accumulatedResults
+  }, [])
+  return filtered
+}
+
+interface PromiseQueueFirstPromiseMakerContext<S = unknown> {
+  index: number
+  hasPreviousResult: false
+  state: S
+}
+interface PromiseQueueRestPromiseMakerContext<V, S = unknown> {
+  index: number
+  hasPreviousResult: true
+  previousResult: V | PromiseFailResult
+  state: S
+}
+type PromiseQueueFirstPromiseMaker<T, S = unknown> = (context: PromiseQueueFirstPromiseMakerContext<S>) => Promise<T>
+type PromiseQueueRestPromiseMaker<T, S = unknown> = (context: PromiseQueueRestPromiseMakerContext<T, S>) => Promise<T>
+type PromiseQueuePromiseMakers<T, S = unknown> = [
+  PromiseQueueFirstPromiseMaker<T, S>,
+  ...PromiseQueueRestPromiseMaker<T, S>[]
+]
+export interface PromiseQueueOptions {
+  /**
+   * @default 0
+   */
+  breakTime?: number
+}
+/**
+ * Execute promise makers in sequence, passing the previous result to the next maker.
+ *
+ * @example
+ * ```
+ * // Expect: [1, 2]
+ * const example1 = await promiseQueue<number>([
+ *   async () => 1,
+ *   async ({ previousResult }) => (isPromiseFailResult(previousResult) ? 0 : previousResult + 1),
+ * ])
+ * ```
+ */
+export const promiseQueue = async <T, S = unknown>(
+  promiseMakers: PromiseQueuePromiseMakers<T, S>,
+  options?: PromiseQueueOptions | undefined,
+): Promise<Array<T | PromiseFailResult>> => {
+  const { breakTime = 0 } = options ?? {}
+  const results: Array<T | PromiseFailResult> = []
+
+  let context: PromiseQueueFirstPromiseMakerContext<S> | PromiseQueueRestPromiseMakerContext<T, S> = {
+    index: 0,
+    hasPreviousResult: false,
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    state: undefined as unknown as S
+  }
+
+  const [firstPromiseMaker, ...restPromiseMakers] = promiseMakers
+  const lastPromise = restPromiseMakers.reduce(async (
+    accumulatedPromise, currentPromiseMaker, index
+  ) => {
+    return await accumulatedPromise
+      .catch(promiseCatchToFailResult)
+      .then(async (result) => {
+        results.push(result)
+        return await new Promise((resolve) => {
+          setTimeout(() => {
+            context = {
+              ...context,
+              index: index + 1,
+              hasPreviousResult: true,
+              previousResult: result
+            }
+            resolve(currentPromiseMaker(context))
+          }, breakTime)
+        })
+      })
+  }, firstPromiseMaker(context))
+
+  await lastPromise
+    .catch(promiseCatchToFailResult)
+    .then((result) => {
+      results.push(result)
+    })
+
+  return results
+}
+
+interface PromiseRetryFirstPromiseMakerContext<S = unknown> {
+  time: number
+  hasPreviousResult: false
+  state: S
+}
+interface PromiseRetryRestPromiseMakerContext<T, S = unknown> {
+  time: number
+  hasPreviousResult: true
+  previousResult: T | PromiseFailResult
+  state: S
+}
+type PromiseRetryPromiseMaker<T, S = unknown> = (
+  context: PromiseRetryFirstPromiseMakerContext<S> | PromiseRetryRestPromiseMakerContext<T, S>
+) => Promise<T>
+export interface PromiseRetryOptions {
+  /**
+   * @default 0
+   */
+  breakTime?: number
+  /**
+   * @default Infinity
+   */
+  maxTryTimes?: number
+}
+/**
+ * Retry while the predicate indicates the result is not acceptable.
+ *
+ * @example
+ * ```
+ * let counter = 0
+ * // Expect: 3
+ * const example1 = await promiseRetryWhile(
+ *   (value) => value < 3,
+ *   async () => {
+ *     counter = counter + 1
+ *     return counter
+ *   },
+ * )
+ * ```
+ *
+ * @see {@link promiseRetryUntil}
+ */
+export const promiseRetryWhile = async <T, S = unknown>(
+  predicate: (value: T) => boolean | Promise<boolean>,
+  promiseMaker: PromiseRetryPromiseMaker<T, S>,
+  options?: PromiseRetryOptions | undefined,
+): Promise<T | PromiseFailResult> => {
+  const {
+    breakTime = 0,
+    maxTryTimes = Infinity,
+  } = options ?? {}
+
+  if (maxTryTimes < 1) {
+    throw new Error("`maxTryTimes` must be greater than 0.")
+  }
+
+  let time = 1
+  // oxlint-disable-next-line no-accumulating-spread
+  let context: PromiseRetryFirstPromiseMakerContext<S> | PromiseRetryRestPromiseMakerContext<T, S> = {
+    time,
+    hasPreviousResult: false,
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    state: undefined as unknown as S
+  }
+  let result = await promiseMaker(context).catch(promiseCatchToFailResult)
+
+  while (
+    (isPromiseFailResult(result) || (await predicate(result)))
+    && time < maxTryTimes
+  ) {
+    time = time + 1
+    // oxlint-disable-next-line no-loop-func
+    result = await new Promise<T | PromiseFailResult>((resolve) => {
+      setTimeout(() => {
+        context = {
+          ...context,
+          time,
+          hasPreviousResult: true,
+          previousResult: result,
+        }
+        resolve(promiseMaker(context))
+      }, breakTime)
+    }).catch(promiseCatchToFailResult)
+  }
+
+  return result
+}
+
+/**
+ * Retry until the predicate returns true for the current result.
+ *
+ * @example
+ * ```
+ * let counter = 0
+ * // Expect: 2
+ * const example1 = await promiseRetryUntil(
+ *   (value) => value >= 2,
+ *   async () => {
+ *     counter = counter + 1
+ *     return counter
+ *   },
+ * )
+ * ```
+ *
+ * @see {@link promiseRetryWhile}
+ */
+export const promiseRetryUntil = async <T, S = unknown>(
+  predicate: (value: T, time: number) => boolean | Promise<boolean>,
+  promiseMaker: PromiseRetryPromiseMaker<T, S>,
+  options?: PromiseRetryOptions | undefined,
+): Promise<T | PromiseFailResult> => {
+  const {
+    breakTime = 0,
+    maxTryTimes = Infinity,
+  } = options ?? {}
+
+  if (maxTryTimes < 1) {
+    throw new Error("`maxTryTimes` must be greater than 0.")
+  }
+
+  let time = 1
+  // oxlint-disable-next-line no-accumulating-spread
+  let context: PromiseRetryFirstPromiseMakerContext<S> | PromiseRetryRestPromiseMakerContext<T, S> = {
+    time,
+    hasPreviousResult: false,
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    state: undefined as unknown as S
+  }
+  let result = await promiseMaker(context).catch(promiseCatchToFailResult)
+
+  while (
+    (isPromiseFailResult(result) || !(await predicate(result, time)))
+    && time < maxTryTimes
+  ) {
+    time = time + 1
+    // oxlint-disable-next-line no-loop-func
+    result = await new Promise<T | PromiseFailResult>((resolve) => {
+      setTimeout(() => {
+        context = {
+          ...context,
+          time,
+          hasPreviousResult: true,
+          previousResult: result
+        }
+        resolve(promiseMaker(context))
+      }, breakTime)
+    }).catch(promiseCatchToFailResult)
+  }
+
+  return result
+}
+
+/**
+ * Start periodic asynchronous execution and return a function to stop it.
+ *
+ * @example
+ * ```
+ * const records: number[] = []
+ * const stop = promiseInterval(10, async (time) => {
+ *   records.push(time)
+ *   return time
+ * })
+ * // Later: stop()
+ * // Expect: typeof stop === "function"
+ * const example1 = typeof stop === "function"
+ * ```
+ */
+export const promiseInterval = <T>(
+  interval: number,
+  promiseMaker: (time: number) => Promise<T>,
+): (() => void) => {
+  let time = 1
+
+  const intervalID = setInterval(() => {
+    void promiseMaker(time)
+    time = time + 1
+  }, interval)
+
+  return () => {
+    clearInterval(intervalID)
+  }
+}
+
+interface PromiseForeverFirstPromiseMakerContext<S = unknown> {
+  time: number
+  hasPreviousResult: false
+  state: S
+}
+interface PromiseForeverRestPromiseMakerContext<T, S = unknown> {
+  time: number
+  hasPreviousResult: true
+  previousResult: T | PromiseFailResult
+  state: S
+}
+type PromiseForeverPromiseMaker<T, S = unknown> = (
+  context: PromiseForeverFirstPromiseMakerContext<S> | PromiseForeverRestPromiseMakerContext<T, S>
+) => Promise<T>
+export interface PromiseForeverOptions {
+  /**
+   * @default 0
+   */
+  breakTime?: number | undefined
+  onRejected?: ((time: number, result: PromiseFailResult) => void) | undefined
+}
+/**
+ * Continuously execute an async maker forever with optional delay and rejection hook.
+ *
+ * @example
+ * ```
+ * let times = 0
+ * promiseForever(async () => {
+ *   times = times + 1
+ *   return times
+ * }, { breakTime: 0 })
+ * // Expect: no return value
+ * const example1 = promiseForever(async () => 1)
+ * ```
+ */
+export const promiseForever = <T, S = unknown>(
+  promiseMaker: PromiseForeverPromiseMaker<T, S>,
+  options?: PromiseForeverOptions | undefined,
+): void => {
+  const {
+    breakTime = 0,
+    onRejected,
+  } = options ?? {}
+
+  let time = 1
+  let context: PromiseForeverFirstPromiseMakerContext<S> | PromiseForeverRestPromiseMakerContext<T, S> = {
+    time,
+    hasPreviousResult: false,
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    state: undefined as unknown as S
+  }
+
+  const handlePromise = (result: T | PromiseFailResult): void => {
+    time = time + 1
+    setTimeout(() => {
+      context = {
+        ...context,
+        time,
+        hasPreviousResult: true,
+        previousResult: result
+      }
+      runPromise(context)
+    }, breakTime)
+  }
+  const runPromise = (
+    context: PromiseForeverFirstPromiseMakerContext<S> | PromiseForeverRestPromiseMakerContext<T, S>
+  ): void => {
+    void promiseMaker(context)
+      // oxlint-disable-next-line prefer-await-to-callbacks
+      .catch((error: unknown) => {
+        const failedResult = promiseCatchToFailResult(error)
+        if (onRejected !== undefined) {
+          try {
+            onRejected(time, failedResult)
+          }
+          catch {
+            // omit exceptions from execution of `onRejected`
+          }
+        }
+        else {
+          console.log("❌ [promiseForever] unexcepted error occured:", failedResult)
+        }
+        return failedResult
+      })
+      .then(result => handlePromise(result))
+  }
+
+  runPromise(context)
+}

package/src/basic/regexp.ts

@@ -0,0 +1,7 @@
+/**
+ * Checks if a string is a valid email address.
+ */
+export const regexpIsEmail = (value: string): boolean => {
+  const emailRegex = /^[\w.%+-]+@[a-z0-9.-]+\.[a-z]{2,}$/i
+  return emailRegex.test(value)
+}