@planet-matrix/mobius-model 0.3.0 → 0.5.0

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

package/src/basic/temporal.ts

@@ -0,0 +1,224 @@
+import { isDate } from "./is.ts"
+
+/**
+ * Check whether a date is outdated (in the past).
+ */
+export const temporalIsOutdated = (target: unknown): boolean => {
+  return isDate(target) && (new Date(target).getTime() < Date.now())
+}
+
+/**
+ * Format a timestamp to a YYYY-MM-DD string.
+ *
+ * @example
+ * ```
+ * // Expect: "1970-01-01"
+ * const example1 = temporalFormatToYYYYMMDD(0)
+ * // Expect: "2000/01/02"
+ * const example2 = temporalFormatToYYYYMMDD(946771200000, "/")
+ * ```
+ */
+export const temporalFormatToYYYYMMDD = (timestamp: number, separator = "-"): string => {
+  const date = new Date(timestamp)
+  const year = date.getFullYear()
+  const month = String(date.getMonth() + 1).padStart(2, "0")
+  const day = String(date.getDate()).padStart(2, "0")
+  return `${year}${separator}${month}${separator}${day}`
+}
+
+/**
+ * Format a timestamp to a hh:mm:ss string.
+ *
+ * @example
+ * ```
+ * // Expect: "00:00:00"
+ * const example1 = temporalFormatTohhmmss(0)
+ * // Expect: "12:34:56"
+ * const example2 = temporalFormatTohhmmss(45296000)
+ * ```
+ */
+export const temporalFormatTohhmmss = (timestamp: number, separator = ":"): string => {
+  const date = new Date(timestamp)
+  const hours = String(date.getHours()).padStart(2, "0")
+  const minutes = String(date.getMinutes()).padStart(2, "0")
+  const seconds = String(date.getSeconds()).padStart(2, "0")
+  return `${hours}${separator}${minutes}${separator}${seconds}`
+}
+
+/**
+ * Format a timestamp to a YYYY-MM-DD hh:mm:ss string.
+ *
+ * @example
+ * ```
+ * // Expect: "1970-01-01 00:00:00"
+ * const example1 = temporalFormatToYYYYMMDDhhmmss(0)
+ * // Expect: "2000-01-02 00:00:00"
+ * const example2 = temporalFormatToYYYYMMDDhhmmss(946771200000)
+ * ```
+ */
+export const temporalFormatToYYYYMMDDhhmmss = (timestamp: number): string => {
+  return `${temporalFormatToYYYYMMDD(timestamp)} ${temporalFormatTohhmmss(timestamp)}`
+}
+
+/**
+ * Format a timestamp to a relative time string (e.g., "刚刚", "5 分钟前").
+ *
+ * @example
+ * ```
+ * // Expect: "刚刚"
+ * const originalNow = Date.now
+ * Date.now = () => 3_600_000
+ * const example1 = temporalFormatToRelativeTime(3_600_000)
+ * // Expect: "1 小时前"
+ * const example2 = temporalFormatToRelativeTime(0)
+ * Date.now = originalNow
+ * ```
+ */
+export const temporalFormatToRelativeTime = (timestamp: number): string => {
+  const now = Date.now()
+  const diffInSeconds = Math.floor((now - timestamp) / 1_000)
+
+  if (diffInSeconds < 60) {
+    return "刚刚"
+  }
+  else if (diffInSeconds < 3_600) {
+    const minutes = Math.floor(diffInSeconds / 60)
+    return `${minutes} 分钟前`
+  }
+  else if (diffInSeconds < 86_400) {
+    const hours = Math.floor(diffInSeconds / 3_600)
+    return `${hours} 小时前`
+  }
+  else if (diffInSeconds < 172_800) {
+    return "昨天"
+  }
+  else if (diffInSeconds < 604_800) {
+    return "一周内"
+  }
+  else {
+    // 格式化为 YYYY-MM-DD hh:ss
+    return temporalFormatToYYYYMMDDhhmmss(timestamp)
+  }
+}
+
+export interface TemporalFormatToWechatRelativeTimeOptions {
+  timestamp: number
+  alwaysShowTime?: boolean | undefined
+}
+/**
+ * Format a timestamp to a WeChat-style relative time string.
+ *
+ * @example
+ * ```
+ * // Expect: "70/01/01"
+ * const example1 = temporalFormatToWechatRelativeTime({ timestamp: 0 })
+ * // Expect: "70/01/01 00:00"
+ * const example2 = temporalFormatToWechatRelativeTime({ timestamp: 0, alwaysShowTime: true })
+ * ```
+ */
+export const temporalFormatToWechatRelativeTime = (
+  options: TemporalFormatToWechatRelativeTimeOptions
+): string => {
+  const {
+    timestamp,
+    alwaysShowTime = false,
+  } = options
+
+  const now = new Date()
+  const targetDate = new Date(timestamp)
+
+  const padZero = (num: number): string => num.toString().padStart(2, "0")
+
+  const isSameDay = (date1: Date, date2: Date): boolean => {
+    return date1.getFullYear() === date2.getFullYear()
+      && date1.getMonth() === date2.getMonth()
+      && date1.getDate() === date2.getDate()
+  }
+
+  const isYesterday = (date1: Date, date2: Date): boolean => {
+    const yesterday = new Date(date1)
+    yesterday.setDate(date1.getDate() - 1)
+    return isSameDay(yesterday, date2)
+  }
+
+  const getWeekDayName = (date: Date): string => {
+    const weekdays = ["星期日", "星期一", "星期二", "星期三", "星期四", "星期五", "星期六"]
+    return weekdays[date.getDay()]!
+  }
+
+  const isSameWeek = (date1: Date, date2: Date): boolean => {
+    const startOfWeek = (date: Date): Date => {
+      const result = new Date(date)
+      const day = result.getDay()
+      const diff = result.getDate() - day + (day === 0 ? -6 : 1)
+      result.setDate(diff)
+      return new Date(result.getFullYear(), result.getMonth(), result.getDate())
+    }
+
+    return startOfWeek(date1).getTime() === startOfWeek(date2).getTime()
+  }
+
+  const date = `${padZero(targetDate.getFullYear() % 100)}/${padZero(targetDate.getMonth() + 1)}/${padZero(targetDate.getDate())}`
+  const time = `${padZero(targetDate.getHours())}:${padZero(targetDate.getMinutes())}`
+
+  if (isSameDay(now, targetDate)) {
+    return time
+  }
+  else if (isYesterday(now, targetDate)) {
+    return alwaysShowTime ? `昨天 ${time}` : "昨天"
+  }
+  else if (isSameWeek(now, targetDate)) {
+    return alwaysShowTime ? `${getWeekDayName(targetDate)} ${time}` : getWeekDayName(targetDate)
+  }
+  else {
+    return alwaysShowTime ? `${date} ${time}` : date
+  }
+}
+
+type InternalUnitsDict = Record<string, string>
+const INTERNAL_UNITS_DICT: InternalUnitsDict = {
+  year: "年",
+  month: "月",
+  week: "周",
+  day: "天",
+  hour: "小时",
+  minute: "分钟",
+  second: "秒",
+  millisecond: "毫秒",
+}
+type InternalUnitsMilliDict = Record<string, number>
+const INTERNAL_UNITS_MILLI_DICT: InternalUnitsMilliDict = {
+  year: 31_557_600_000,
+  month: 2_629_800_000,
+  week: 604_800_000,
+  day: 86_400_000,
+  hour: 3_600_000,
+  minute: 60_000,
+  second: 1_000,
+  millisecond: 1,
+}
+/**
+ * Convert a timestamp to a human-readable relative time string in Chinese.
+ *
+ * @example
+ * ```
+ * // Expect: "刚刚"
+ * const originalNow = Date.now
+ * Date.now = () => 3_600_000
+ * const example1 = temporalHumanize(3_600_000)
+ * // Expect: "1 小时前"
+ * const example2 = temporalHumanize(0)
+ * Date.now = originalNow
+ * ```
+ */
+export const temporalHumanize = (timestamp: number): string => {
+  let res = ""
+  const milliseconds = Date.now() - timestamp
+  for (const key in INTERNAL_UNITS_MILLI_DICT) {
+    if (milliseconds >= INTERNAL_UNITS_MILLI_DICT[key]!) {
+      res = `${Math.floor(milliseconds / INTERNAL_UNITS_MILLI_DICT[key]!)} ${INTERNAL_UNITS_DICT[key]}前`
+      break
+    }
+  }
+  return res !== "" ? res : "刚刚"
+}