@planet-matrix/mobius-model 0.3.0 → 0.4.0

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

package/src/basic/string.ts

@@ -0,0 +1,308 @@
+const internalRandomPacket: Record<number, string[]> = {}
+/**
+ * Generate a random string with a fixed length and optional character set.
+ *
+ * @example
+ * ```
+ * // Expect: 8
+ * const example1 = stringRandom(8).length
+ * // Expect: true
+ * const example2 = stringRandom(4, "ab").split("").every(char => char === "a" || char === "b")
+ * ```
+ */
+export const stringRandom = (length: number, chars?: string | undefined): string => {
+  let result = ""
+  const preparedChars = chars ?? "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
+
+  Array.from({ length }).forEach(() => {
+    result = result + preparedChars[Math.floor(Math.random() * preparedChars.length)]!
+  })
+
+  internalRandomPacket[length] = internalRandomPacket[length] ?? []
+  const packet = internalRandomPacket[length]
+  if (packet.includes(result)) {
+    return stringRandom(length, preparedChars)
+  }
+  else {
+    packet.push(result)
+    return result
+  }
+}
+
+/**
+ * Convert a camelCase string into kebab-case.
+ *
+ * @example
+ * ```
+ * // Expect: "hello-world"
+ * const example1 = stringCamelCaseToKebabCase("helloWorld")
+ * // Expect: "ab2-cd"
+ * const example2 = stringCamelCaseToKebabCase("ab2Cd")
+ * ```
+ */
+export const stringCamelCaseToKebabCase = (camelCase: string): string => {
+  return camelCase.replaceAll(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase()
+}
+
+/**
+ * Convert a kebab-case string into camelCase.
+ *
+ * @example
+ * ```
+ * // Expect: "helloWorld"
+ * const example1 = stringKebabCaseToCamelCase("hello-world")
+ * // Expect: "ab2Cd"
+ * const example2 = stringKebabCaseToCamelCase("ab2-cd")
+ * ```
+ */
+export const stringKebabCaseToCamelCase = (kebabCase: string): string => {
+  return kebabCase.replaceAll(/-./g, x => x[1]!.toUpperCase())
+}
+
+/**
+ * Get a greeting based on the current local hour.
+ *
+ * @example
+ * ```
+ * // Expect: "你好" | "早上好" | "晚上好" | ...
+ * const example1 = stringHelloWord()
+ * ```
+ */
+export const stringHelloWord = (): string => {
+  const currentHour = new Date().getHours()
+  if (currentHour < 5) {
+    return "凌晨好"
+  }
+  if (currentHour < 8) {
+    return "早上好"
+  }
+  if (currentHour < 12) {
+    return "上午好"
+  }
+  if (currentHour < 14) {
+    return "中午好"
+  }
+  if (currentHour < 17) {
+    return "下午好"
+  }
+  if (currentHour < 19) {
+    return "傍晚好"
+  }
+  if (currentHour < 24) {
+    return "晚上好"
+  }
+  return "你好"
+}
+
+/**
+ * Calculate the total unit length of a string.
+ *
+ * @example
+ * ```
+ * // Expect: 1.5
+ * const example1 = stringCalculateUnits("a中")
+ * // Expect: 2
+ * const example2 = stringCalculateUnits("中文")
+ * ```
+ */
+export const stringCalculateUnits = (text: string): number => {
+  let units = 0
+
+  for (const char of text) {
+    if (/[\u0000-\u007F]/.test(char)) {
+      // Half-width character (e.g., ASCII)
+      units = units + 0.5
+    }
+    else {
+      // Full-width character (e.g., CJK)
+      units = units + 1
+    }
+  }
+
+  return units
+}
+
+/**
+ * Truncate a string by the unit limit and keep whole characters.
+ *
+ * @example
+ * ```
+ * // Expect: "a中"
+ * const example1 = stringTruncateByUnits("a中文", 1.5)
+ * // Expect: "abc"
+ * const example2 = stringTruncateByUnits("abc", 2)
+ * ```
+ */
+export const stringTruncateByUnits = (text: string, maxUnits: number): string => {
+  let truncated = ""
+  let units = 0
+
+  for (const char of text) {
+    const charUnits = /[\u0000-\u007F]/.test(char) ? 0.5 : 1
+    if (units + charUnits > maxUnits) { break }
+
+    truncated = truncated + char
+    units = units + charUnits
+  }
+
+  return truncated
+}
+
+/**
+ * Slice a string by unit indices.
+ *
+ * @example
+ * ```
+ * // Expect: "a中"
+ * const example1 = stringSliceByUnits("a中文", 0, 1.5)
+ * // Expect: "文"
+ * const example2 = stringSliceByUnits("中文ab", 1, 2)
+ * ```
+ */
+export const stringSliceByUnits = (text: string, start: number, end: number): string => {
+  let units = 0
+  let result = ""
+  for (const char of text) {
+    const charUnits = /[\u0000-\u007F]/.test(char) ? 0.5 : 1
+    if (units >= end) { break }
+
+    if (units >= start) {
+      result = result + char
+    }
+    units = units + charUnits
+  }
+
+  return result
+}
+
+export interface StringSplitOptions {
+  input: string
+  chunkSize: number
+  chunkOverlap: number
+}
+
+/**
+ * Split a long string into fixed-size chunks with optional overlap.
+ *
+ * @example
+ * ```
+ * // Expect: ["hello", "lo wo", "world"]
+ * const example1 = stringSplit({ input: "hello world", chunkSize: 5, chunkOverlap: 2 })
+ * ```
+ */
+export const stringSplit = (options: StringSplitOptions): string[] => {
+  const { input, chunkSize = 1_500, chunkOverlap: overlap = 20 } = options
+  const safeChunkSize = Math.max(1, Math.trunc(chunkSize))
+  const safeOverlap = Math.max(0, Math.min(Math.trunc(overlap), safeChunkSize - 1))
+
+  // 去除换行符和其他特殊符号
+  const sanitizedInput = input.replaceAll(/[\t\n\r]/g, " ")
+
+  // 分割结果数组
+  const result: string[] = []
+
+  // 当前处理位置
+  let currentPosition = 0
+
+  // 循环处理整个输入字符串
+  while (currentPosition < sanitizedInput.length) {
+    // 计算当前片段的结束位置
+    const endPosition = Math.min(currentPosition + safeChunkSize, sanitizedInput.length)
+
+    // 获取当前片段
+    const segment = sanitizedInput.slice(currentPosition, endPosition)
+
+    // 将当前片段添加到结果数组中
+    result.push(segment)
+
+    // 如果已经到达文本末尾，退出循环
+    if (endPosition >= sanitizedInput.length) {
+      break
+    }
+
+    // 更新处理位置，有重叠部分
+    currentPosition = endPosition - safeOverlap
+  }
+
+  return result
+}
+
+/**
+ * Split a string into chunks while trying to keep natural line breaks.
+ *
+ * @example
+ * ```
+ * // Expect: ["a\\n", "b\\n", "c"]
+ * const example1 = stringSmartSplit("a\nb\nc", 2)
+ * ```
+ */
+export const stringSmartSplit = (text: string, maxLength: number): string[] => {
+  let _text = text
+  if (_text.length <= maxLength) {
+    return [_text]
+  }
+
+  const conservativeMaxLength = maxLength * 0.9
+
+  const threshold = maxLength * 0.2
+  const texts: string[] = []
+  while (_text.length > conservativeMaxLength) {
+    texts.push(_text.slice(0, conservativeMaxLength))
+    _text = _text.slice(conservativeMaxLength)
+  }
+  if (_text.length > threshold) {
+    texts.push(_text)
+  }
+  else {
+    texts[texts.length - 1] = texts.at(-1)! + _text
+  }
+
+  if (texts.length === 1) {
+    return texts
+  }
+
+  for (let i = 1; i < texts.length; i = i + 1) {
+    const previousText = texts[i - 1]!
+    const currentText = texts[i]!
+    const lastIndexOfNewLineOfPreviousText = previousText.lastIndexOf("\n")
+    const firstIndexOfNewLineOfCurrentText = currentText.indexOf("\n")
+    const endOfPreviousText = previousText.slice(lastIndexOfNewLineOfPreviousText + 1)
+    const startOfCurrentText = currentText.slice(0, firstIndexOfNewLineOfCurrentText)
+    if (endOfPreviousText.length >= startOfCurrentText.length) {
+      const newPreviousText = previousText + startOfCurrentText
+      const newCurrentText = currentText.slice(firstIndexOfNewLineOfCurrentText + 1)
+      texts[i - 1] = newPreviousText
+      texts[i] = newCurrentText
+    }
+    else {
+      const newPreviousText = previousText.slice(0, lastIndexOfNewLineOfPreviousText)
+      const newCurrentText = endOfPreviousText + currentText
+      texts[i - 1] = newPreviousText
+      texts[i] = newCurrentText
+    }
+  }
+
+  const trimmedTexts = texts.map(text => text.trim())
+
+  return trimmedTexts
+}
+
+/**
+ * Truncate a string to a maximum length with an ellipsis.
+ *
+ * @example
+ * ```
+ * // Expect: "hello..."
+ * const example1 = stringTruncate("hello world", 5)
+ * // Expect: "hi"
+ * const example2 = stringTruncate("hi", 5)
+ * ```
+ */
+export const stringTruncate = (str: string, n: number): string => {
+  if (str.length <= n) {
+    return str
+  }
+  else {
+    return `${str.slice(0, n)}...`
+  }
+}

package/src/basic/symbol.ts

@@ -0,0 +1,164 @@
+import { isSymbol } from "./is.ts"
+
+/**
+ * Create a new unique symbol with an optional description.
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = typeof symbolCreateLocal("demo") === "symbol"
+ * // Expect: false
+ * const example2 = symbolCreateLocal("demo") === symbolCreateLocal("demo")
+ * ```
+ */
+export const symbolCreateLocal = (description?: string): symbol => {
+  return Symbol(description)
+}
+
+/**
+ * Get or create a global symbol for the given key.
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = symbolCreateGlobal("demo") === Symbol.for("demo")
+ * // Expect: true
+ * const example2 = symbolCreateGlobal("demo") === symbolCreateGlobal("demo")
+ * ```
+ */
+export const symbolCreateGlobal = (key: string): symbol => Symbol.for(key)
+
+/**
+ * Get the key for a global symbol, or undefined if not global.
+ *
+ * @example
+ * ```
+ * // Expect: "demo"
+ * const example1 = symbolGetKey(Symbol.for("demo"))
+ * // Expect: undefined
+ * const example2 = symbolGetKey(Symbol("demo"))
+ * ```
+ */
+export const symbolGetKey = (value: unknown): string | undefined => {
+  return isSymbol(value) ? Symbol.keyFor(value) : undefined
+}
+
+/**
+ * Check whether a symbol is from the global registry.
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = symbolIsGlobal(Symbol.for("demo"))
+ * // Expect: false
+ * const example2 = symbolIsGlobal(Symbol("demo"))
+ * ```
+ */
+export const symbolIsGlobal = (value: unknown): value is symbol => {
+  return isSymbol(value) && Symbol.keyFor(value) !== undefined
+}
+
+/**
+ * Check whether a symbol is not from the global registry.
+ *
+ * @example
+ * ```
+ * // Expect: false
+ * const example1 = symbolIsLocal(Symbol.for("demo"))
+ * // Expect: true
+ * const example2 = symbolIsLocal(Symbol("demo"))
+ * ```
+ */
+export const symbolIsLocal = (value: unknown): value is symbol => {
+  return isSymbol(value) && Symbol.keyFor(value) === undefined
+}
+
+/**
+ * Check whether a symbol has a description.
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = symbolHasDescription(Symbol("demo"))
+ * // Expect: false
+ * const example2 = symbolHasDescription(Symbol())
+ * ```
+ */
+export const symbolHasDescription = (value: unknown): value is symbol => {
+  return isSymbol(value) && value.description !== undefined
+}
+
+/**
+ * Get the description of a symbol, or undefined for non-symbols.
+ *
+ * @example
+ * ```
+ * // Expect: "demo"
+ * const example1 = symbolGetDescription(Symbol("demo"))
+ * // Expect: undefined
+ * const example2 = symbolGetDescription(Symbol())
+ * ```
+ */
+export const symbolGetDescription = (value: unknown): string | undefined => {
+  return isSymbol(value) ? value.description : undefined
+}
+
+/**
+ * Check whether a symbol is anonymous (no description).
+ *
+ * @example
+ * ```
+ * // Expect: false
+ * const example1 = symbolIsAnonymous(Symbol("demo"))
+ * // Expect: true
+ * const example2 = symbolIsAnonymous(Symbol())
+ * ```
+ */
+export const symbolIsAnonymous = (value: unknown): value is symbol => {
+  return isSymbol(value) && value.description === undefined
+}
+
+const internalWellKnownSymbols = new Set<symbol>([
+  Symbol.asyncIterator,
+  Symbol.hasInstance,
+  Symbol.isConcatSpreadable,
+  Symbol.iterator,
+  Symbol.match,
+  Symbol.matchAll,
+  Symbol.replace,
+  Symbol.search,
+  Symbol.species,
+  Symbol.split,
+  Symbol.toPrimitive,
+  Symbol.toStringTag,
+  Symbol.unscopables,
+])
+/**
+ * Check whether a symbol is one of the well-known symbols.
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = symbolIsWellKnown(Symbol.iterator)
+ * // Expect: false
+ * const example2 = symbolIsWellKnown(Symbol("iterator"))
+ * ```
+ */
+export const symbolIsWellKnown = (value: unknown): value is symbol => {
+  return isSymbol(value) && internalWellKnownSymbols.has(value)
+}
+
+/**
+ * Convert a symbol to its string representation.
+ *
+ * @example
+ * ```
+ * // Expect: "Symbol(demo)"
+ * const example1 = symbolToString(Symbol("demo"))
+ * // Expect: undefined
+ * const example2 = symbolToString("demo")
+ * ```
+ */
+export const symbolToString = (value: unknown): string | undefined => {
+  return isSymbol(value) ? value.toString() : undefined
+}