@planet-matrix/mobius-model 0.3.0 → 0.5.0

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)
+}

package/src/basic/stream.ts

@@ -0,0 +1,140 @@
+import type { ReadableStreamController, ReadableStreamReadResult } from "node:stream/web"
+
+import { ReadableStream } from "node:stream/web"
+
+/**
+ * 从数组创建一个 ReadableStream。
+ */
+export const streamFromArray = <T>(values: T[]): ReadableStream<T> => {
+  const stream = new ReadableStream<T>({
+    start(controller): void {
+      for (const value of values) {
+        controller.enqueue(value)
+      }
+      controller.close()
+    },
+  })
+  return stream
+}
+
+export interface StreamConsumeInSyncMacroTaskOptions<T> {
+  readableStream: ReadableStream<T>
+  onValue?: ((chunk: T) => (void | Promise<void>)) | undefined
+  onDone?: (() => (void | Promise<void>)) | undefined
+  onError?: ((error: Error) => (void | Promise<void>)) | undefined
+}
+/**
+ * 在同步宏任务中完成 ReadableStream 的消费。
+ */
+export const streamConsumeInSyncMacroTask = async <T>(
+  options: StreamConsumeInSyncMacroTaskOptions<T>,
+): Promise<void> => {
+  const { readableStream, onValue, onDone, onError } = options
+
+  try {
+    for await (const chunk of readableStream) {
+      await onValue?.(chunk)
+    }
+    await onDone?.()
+  }
+  catch (exception) {
+    console.error(`Error reading stream: ${String(exception)}`)
+    await onError?.(new Error(`Error reading stream: ${String(exception)}`))
+  }
+}
+
+export interface StreamConsumeInAsyncMacroTaskOptions<T> {
+  readableStream: ReadableStream<T>
+  onValue?: ((chunk: T) => (void | Promise<void>)) | undefined
+  onDone?: (() => (void | Promise<void>)) | undefined
+  onError?: ((error: Error) => (void | Promise<void>)) | undefined
+}
+/**
+ * 在异步宏任务中完成 ReadableStream 的消费。
+ */
+export const streamConsumeInAsyncMacroTask = <T>(
+  options: StreamConsumeInAsyncMacroTaskOptions<T>,
+): void => {
+  const { readableStream, onValue, onDone, onError } = options
+
+  const reader = readableStream.getReader()
+  const read = (): void => {
+    setTimeout(() => {
+      void reader.read()
+        .then(async (chunk) => {
+          const { done, value } = chunk
+          if (done === true) {
+            await onDone?.()
+            return
+          }
+          await onValue?.(value)
+          read()
+        })
+        .catch(async (reason: unknown) => {
+          await onError?.(new Error(String(reason)))
+        })
+    }, 0)
+  }
+  read()
+}
+
+export interface StreamTransformInAsyncMacroTaskOptions<T, U> {
+  readableStream?: ReadableStream<T> | undefined
+  reader?: ReadableStreamDefaultReader<T> | undefined
+  onChunk?: ((chunk: ReadableStreamReadResult<T>, controller: ReadableStreamDefaultController<U>) => (void | Promise<void>)) | undefined
+  onError?: ((error: Error) => (void | Error | Promise<void | Error>)) | undefined
+}
+/**
+ * 在宏任务队列中完成 ReadableStream 到另一个 ReadableStream 的转换。
+ */
+export const streamTransformInAsyncMacroTask = <T, U>(
+  options: StreamTransformInAsyncMacroTaskOptions<T, U>,
+): ReadableStream<U> => {
+  const { readableStream, reader, onChunk, onError } = options
+
+  if (reader === undefined && readableStream === undefined) {
+    throw new Error("Either readableStream or reader must be provided")
+  }
+
+  const preparedReader = reader ?? readableStream!.getReader()
+  const stream = new ReadableStream<U>({
+    start(controller): void {
+      const read = (): void => {
+        setTimeout(() => {
+          void preparedReader.read()
+            .then(async (chunk) => {
+              let shouldContinue = true
+              const proxyController: ReadableStreamController<U> = {
+                // oxlint-disable-next-line no-misused-spread
+                ...controller,
+                enqueue: (chunk: U): void => {
+                  controller.enqueue(chunk)
+                  shouldContinue = true
+                },
+                close: (): void => {
+                  controller.close()
+                  shouldContinue = false
+                },
+                error: (error: Error): void => {
+                  controller.error(error)
+                  shouldContinue = false
+                },
+              }
+              await onChunk?.(chunk, proxyController)
+              if (shouldContinue === true) {
+                read()
+              }
+            })
+            .catch(async (reason: unknown) => {
+              const error = new Error(String(reason))
+              const refinedError = await onError?.(error)
+              controller.error(refinedError ?? error)
+            })
+        }, 0)
+      }
+      read()
+    },
+  })
+
+  return stream
+}