@planet-matrix/mobius-model 0.6.0 → 0.10.1

package/src/exception/error/must-fix.ts

@@ -0,0 +1,17 @@
+import { createTaggedError } from "./error.ts"
+import type { TaggedErrorConstructor } from "./error.ts"
+
+const MustFixErrorBase: TaggedErrorConstructor<"MustFix", {
+  message: string
+  cause?: unknown
+}> = createTaggedError("MustFix")()
+export class MustFixError extends MustFixErrorBase {
+  //
+}
+
+export const mustFixError = (message: string, options?: { cause?: unknown }): MustFixError => {
+  return new MustFixError({ message, cause: options?.cause })
+}
+export const isMustFixError = (error: unknown): error is MustFixError => {
+  return MustFixError.is(error)
+}

package/src/exception/index.ts

@@ -2,3 +2,5 @@ export type * from "./types.ts"
 export * from "./normalize.ts"
 export * from "./browser.ts"
 export * from "./nodejs.ts"
+
+export * from "./error/index.ts"

package/src/file-system/find.ts

@@ -0,0 +1,53 @@
+import { statSync } from "node:fs"
+import { dirname, join, parse, resolve } from "node:path"
+import type { ResolveFriendlyOptions } from "./resolve.ts"
+import { resolveStartPath } from "./resolve.ts"
+
+export interface GetClosestFilePathOptions extends ResolveFriendlyOptions {
+  targetBase: string
+}
+/**
+ * 从 {@link ResolveFriendlyOptions.startPath} 开始，逐级向上查找，直到找到指定的文件为止，并返回该文件的路径。
+ * 若未找到指定的文件，则返回 undefined。
+ */
+export const getClosestFilePath = (
+  options: GetClosestFilePathOptions
+): string | undefined => {
+  const { targetBase } = options
+
+  const startPath = resolveStartPath(options)
+
+  let currentDir = startPath
+
+  try {
+    const stat = statSync(startPath)
+    if (stat.isFile()) {
+      currentDir = dirname(startPath)
+    }
+  } catch {
+    currentDir = dirname(startPath)
+  }
+
+  const { root } = parse(currentDir)
+
+  while (true) {
+    const filePath = resolve(join(currentDir, targetBase))
+
+    try {
+      const stat = statSync(filePath)
+      if (stat.isFile()) {
+        return filePath
+      }
+    } catch {
+      //
+    }
+
+    if (currentDir === root) {
+      break
+    }
+
+    currentDir = dirname(currentDir)
+  }
+
+  return undefined
+}

package/src/file-system/index.ts

@@ -0,0 +1,2 @@
+export * from "./path.ts"
+export * from "./find.ts"

package/src/file-system/path.ts

@@ -0,0 +1,76 @@
+import { join, parse } from "node:path"
+import { fileURLToPath } from "node:url"
+
+export type PathString = string
+export interface PathObject {
+  path: string
+  root: string
+  dir: string
+  base: string
+  ext: string
+  name: string
+  separator: string
+}
+export type PathUnion = PathString | PathObject
+
+export const pathStringToObject = (pathString: string): PathObject => {
+  const pathObject = parse(pathString)
+
+  return {
+    root: pathObject.root,
+    path: pathString,
+    dir: pathObject.dir,
+    base: pathObject.base,
+    ext: pathObject.ext,
+    name: pathObject.name,
+    separator: join("a", "b").replaceAll('a', "").replaceAll('b', "")
+  }
+}
+
+export const pathObjectToString = (pathObject: PathObject): string => {
+  return pathObject.path
+}
+
+export const toPathObject = (path: PathUnion): PathObject => {
+  if (typeof path === "string") {
+    if (isFileUrl(path)) {
+      return fileUrlToPathObject(path)
+    } else {
+      return pathStringToObject(path)
+    }
+  } else {
+    return path
+  }
+}
+
+export const toPathString = (path: PathUnion): string => {
+  if (typeof path === "string") {
+    if (isFileUrl(path)) {
+      return fileUrlToPathString(path)
+    } else {
+      return path
+    }
+  } else {
+    return pathObjectToString(path)
+  }
+}
+
+export const isFileUrl = (url: string): boolean => {
+  try {
+    const parsedUrl = new URL(url)
+    return parsedUrl.protocol === "file:"
+  } catch {
+    return false
+  }
+}
+
+export const fileUrlToPathString = (fileUrl: string): PathString => {
+  return fileURLToPath(fileUrl)
+}
+
+export const fileUrlToPathObject = (fileUrl: string): PathObject => {
+  const pathString = fileUrlToPathString(fileUrl)
+  const pathObject = pathStringToObject(pathString)
+
+  return pathObject
+}

package/src/file-system/resolve.ts

@@ -0,0 +1,22 @@
+import { isAbsolute, join, resolve } from "node:path"
+
+export interface ResolveFriendlyOptions {
+  startPath?: string | undefined
+}
+export const resolveStartPath = (options: ResolveFriendlyOptions): string => {
+  const { startPath } = options
+
+  if (startPath === undefined) {
+    return getCurrentWorkingDirectory()
+  }
+
+  if (isAbsolute(startPath)) {
+    return startPath
+  }
+
+  return resolve(join(getCurrentWorkingDirectory(), startPath))
+}
+
+export const getCurrentWorkingDirectory = (): string => {
+  return process.cwd()
+}

package/src/form/README.md

@@ -0,0 +1,25 @@
+# Form
+
+## Description
+
+Form 模块提供围绕类表单输入项（form-like input）及其组合关系的通用建模能力，用于表达输入状态、值转换与聚合边界。
+
+它关注的不是某个组件库的渲染细节，也不是某个框架各自的表单接入方式，而是“一个输入项应如何被视为可独立管理的输入原子、多个输入项如何组合成更高层的类表单数据管理器、以及输入值与聚合值如何保持清楚且可维护的对应关系”这一类基础问题。它之所以被命名为 Form，不是因为它只服务于页面表单，而是因为表单场景最自然、最直观地体现了这类模型的价值。
+
+## For Understanding
+
+理解 Form 模块时，首先应把它看成“类表单数据管理模型”，而不是“页面表单组件集合”或“校验规则工具箱”。它要解决的问题，不是把某个现成表单 API 重新包装一遍，而是为输入项本身建立稳定语义：一个输入项有哪些核心状态，输入过程与最终值如何区分，多个输入项如何组合，以及组合之后的整体值应如何被表达。
+
+这个模块更适合放在以下边界中：
+
+- 你希望把输入逻辑从具体接入层中抽离出来，让输入状态、值更新和聚合关系可以在不同 UI、服务端流程或其它非界面场景之间复用。
+- 你需要先把输入项视为一组可独立管理的输入原子，再把它们组合成更高层的类表单数据管理器，而不是一开始就把所有逻辑揉成单个大对象。
+- 你需要明确区分“输入过程中的值”和“对外稳定表达的值”，并希望这种区分能够成为长期可维护的公共语义。
+
+理解这个模块时，还应守住几条边界原则：
+
+- Form 模块表达的是输入项状态、输入项组合与值映射语义，不负责页面布局、样式、校验文案或具体提交流程。
+- 它可以服务于具体输入组件，但不应因为适配某个框架或某种表单交互习惯，而把这些宿主细节直接上升为模块公共语义。
+- 它关注的是“输入项如何被建模、如何更新、如何聚合”，而不是所有表单相关问题的总容器；像复杂校验编排、错误展示策略、网络提交流程或业务字段规范，通常应由更上层模块承担。
+
+因此，更合适的理解方式是：Form 模块提供的是一套围绕输入原子与类表单聚合的数据管理基础模型能力。表单只是它最典型的落点之一，而不是它的唯一归宿。只有当某个能力确实在澄清这条边界时，它才适合作为该模块的组成部分；如果某个能力只是某类页面表单的临时便利封装，那么它通常不应直接进入这个模块。

package/src/form/index.ts

@@ -0,0 +1 @@
+export * from "./inputor-controller/index.ts"