@planet-matrix/mobius-model 0.6.0 → 0.9.0

package/src/credential/api-key.ts

@@ -0,0 +1,158 @@
+const internalApiKeyAlphabet = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+const internalApiKeyPrefix = "sk-"
+const internalApiKeyBodyLength = 48
+
+interface InternalApiKeyFormat {
+  prefix: string
+  alphabet: string
+  bodyLength: number
+}
+
+// API key 的生成依赖安全随机源。
+// 这个辅助函数同时负责长度校验和随机字节填充，使 API key 生成逻辑可以直接建立在“安全随机字节”之上。
+const internalGetApiKeyRandomValues = (length: number): Uint8Array => {
+  if (Number.isInteger(length) === false || length <= 0) {
+    throw new RangeError(`Expected length to be a positive integer, got: ${length}`)
+  }
+
+  if (globalThis.crypto === undefined || typeof globalThis.crypto.getRandomValues !== "function") {
+    throw new Error("Credential utilities require crypto.getRandomValues")
+  }
+
+  const buffer = new Uint8Array(length)
+  globalThis.crypto.getRandomValues(buffer)
+  return buffer
+}
+
+// API key 的生成与校验必须共享同一份格式定义。
+// 这个辅助函数负责补齐默认值并统一校验前缀、字符集和主体长度，避免生成与遮罩对“合法 key”的理解出现分叉。
+const internalResolveApiKeyFormat = (options: GenerateApiKeyOptions | undefined): InternalApiKeyFormat => {
+  const prefix = options?.prefix ?? internalApiKeyPrefix
+  const alphabet = options?.alphabet ?? internalApiKeyAlphabet
+  const bodyLength = options?.bodyLength ?? internalApiKeyBodyLength
+
+  if (prefix.length === 0) {
+    throw new RangeError("Expected prefix to contain at least one character")
+  }
+
+  if (alphabet.length === 0) {
+    throw new RangeError("Expected alphabet to contain at least one character")
+  }
+
+  if (Number.isInteger(bodyLength) === false || bodyLength <= 0) {
+    throw new RangeError(`Expected bodyLength to be a positive integer, got: ${bodyLength}`)
+  }
+
+  return {
+    prefix,
+    alphabet,
+    bodyLength,
+  }
+}
+
+// Step 1: 校验输入值是否满足 API key 格式约定。
+//
+// 遮罩 API key 时需要按固定位置保留前缀和尾部字符，因此必须先确认输入值符合预期长度和前缀规则。
+const internalAssertApiKey = (apiKey: string, format: InternalApiKeyFormat): void => {
+  const expectedLength = format.prefix.length + format.bodyLength
+
+  if (
+    apiKey.startsWith(format.prefix) === false
+    || apiKey.length !== expectedLength
+  ) {
+    throw new Error("Invalid API key format")
+  }
+
+  const body = apiKey.slice(format.prefix.length)
+
+  for (const character of body) {
+    if (format.alphabet.includes(character) === false) {
+      throw new Error("Invalid API key format")
+    }
+  }
+}
+
+// Step 2: 生成 API key 的随机主体。
+//
+// 该实现直接把安全随机字节映射为 API key 字符，避免把凭据格式语义拆散到通用随机能力之外。
+// 读者只需要理解一个规则：每个随机字节都会被转换成允许字符集中的一个字符。
+const internalGenerateApiKeyBody = (alphabet: string, bodyLength: number): string => {
+  const randomValues = internalGetApiKeyRandomValues(bodyLength)
+  let result = ""
+
+  for (const value of randomValues) {
+    result = result + alphabet[value % alphabet.length]!
+  }
+
+  return result
+}
+
+/**
+ * API key 生成选项。
+ *
+ * `prefix` 用于指定凭据前缀，`alphabet` 用于指定主体字符集，`bodyLength` 用于指定主体长度。
+ * 未提供的字段会分别回退到默认前缀、默认字符集和默认主体长度。
+ */
+export interface GenerateApiKeyOptions {
+  prefix?: string | undefined
+  alphabet?: string | undefined
+  bodyLength?: number | undefined
+}
+
+/**
+ * 生成 API key 字符串，并允许调用方覆写前缀、字符集和主体长度。
+ *
+ * 该函数使用运行时提供的安全随机源生成固定长度的凭据文本，适合在需要不透明访问凭据的边界层生成新 key。
+ *
+ * @example
+ * ```
+ * const apiKey = generateApiKey({})
+ * // Expect: true
+ * const example1 = apiKey.startsWith("sk-")
+ * // Expect: 51
+ * const example2 = apiKey.length
+ * const customApiKey = generateApiKey({ prefix: "pk_", alphabet: "ABC123", bodyLength: 8 })
+ * // Expect: true
+ * const example3 = customApiKey.startsWith("pk_")
+ * // Expect: 11
+ * const example4 = customApiKey.length
+ * ```
+ */
+export const generateApiKey = (options: GenerateApiKeyOptions): string => {
+  const { prefix, alphabet, bodyLength } = internalResolveApiKeyFormat(options)
+
+  return `${prefix}${internalGenerateApiKeyBody(alphabet, bodyLength)}`
+}
+
+/**
+ * 遮罩 API key 的中间部分，保留前缀与末尾少量可见字符。
+ *
+ * 当输入值不满足当前 API key 格式约定时，该函数会抛出 Error。
+ * 若 API key 使用了非默认前缀、字符集或主体长度，应传入同一份格式选项以保持生成与遮罩语义一致。
+ *
+ * @example
+ * ```
+ * // Expect: "sk-ab********************************************yz"
+ * const example1 = maskApiKey("sk-ab0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklyz")
+ * const customOptions = { prefix: "pk_", alphabet: "ABC123", bodyLength: 6 }
+ * // Expect: "pk_AB**23"
+ * const example2 = maskApiKey("pk_ABC123", customOptions)
+ * // Expect: throws Error
+ * const example3 = () => maskApiKey("not-an-api-key")
+ * ```
+ */
+export const maskApiKey = (apiKey: string, options?: GenerateApiKeyOptions): string => {
+  const format = internalResolveApiKeyFormat(options)
+
+  internalAssertApiKey(apiKey, format)
+
+  // 保留前缀可以帮助识别凭据类型，保留末尾少量字符可以帮助区分不同的 key。
+  // 遮罩中间主体可以降低 API key 在日志、报错信息或界面中被完整泄露的风险。
+  const visibleBodyStartLength = Math.min(2, format.bodyLength)
+  const visibleBodyEndLength = Math.min(2, Math.max(0, format.bodyLength - visibleBodyStartLength))
+  const visibleStart = apiKey.slice(0, format.prefix.length + visibleBodyStartLength)
+  const visibleEnd = visibleBodyEndLength === 0 ? "" : apiKey.slice(-visibleBodyEndLength)
+  const maskedPart = "*".repeat(Math.max(0, format.bodyLength - visibleBodyStartLength - visibleBodyEndLength))
+
+  return `${visibleStart}${maskedPart}${visibleEnd}`
+}

package/src/credential/bearer.ts

@@ -0,0 +1,73 @@
+const internalCredentialBearerRegexp = /^Bearer\s+(.+)$/i
+
+// Bearer credential 的标准文本形态是 "Bearer <token>"。
+// 这个辅助函数统一去掉多余空白和 Bearer 前缀，使判断、格式化和解析共享同一条规范化规则。
+const internalNormalizeBearerToken = (token: string): string => {
+  return token.trim().replace(/^Bearer\s+/i, "")
+}
+
+/**
+ * 判断输入值是否为 Bearer 凭据字符串。
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = isBearerCredential("Bearer token-value")
+ * // Expect: false
+ * const example2 = isBearerCredential("Basic token-value")
+ * ```
+ */
+export const isBearerCredential = (input: string): boolean => {
+  return internalCredentialBearerRegexp.test(input.trim())
+}
+
+/**
+ * 把原始 token 格式化为 Bearer 凭据字符串。
+ *
+ * 当输入值只包含空白字符时，该函数会抛出 RangeError，避免产出一个连 Bearer 校验器都不会接受的无效凭据字符串。
+ *
+ * @example
+ * ```
+ * // Expect: "Bearer token-value"
+ * const example1 = formatBearerCredential("token-value")
+ * // Expect: "Bearer token-value"
+ * const example2 = formatBearerCredential("  token-value  ")
+ * // Expect: throws RangeError
+ * const example3 = () => formatBearerCredential("   ")
+ * ```
+ */
+export const formatBearerCredential = (token: string): string => {
+  const normalizedToken = internalNormalizeBearerToken(token)
+
+  if (normalizedToken.length === 0) {
+    throw new RangeError("Expected token to contain at least one non-whitespace character")
+  }
+
+  return `Bearer ${normalizedToken}`
+}
+
+/**
+ * 从 Bearer 凭据字符串中提取原始 token。
+ *
+ * 当输入值不是 Bearer 格式时，该函数返回 `undefined`。
+ *
+ * @example
+ * ```
+ * // Expect: "token-value"
+ * const example1 = parseBearerCredential("Bearer token-value")
+ * // Expect: undefined
+ * const example2 = parseBearerCredential("Basic token-value")
+ * ```
+ */
+export const parseBearerCredential = (input: string | undefined): string | undefined => {
+  if (input === undefined) {
+    return undefined
+  }
+
+  if (isBearerCredential(input) === false) {
+    return undefined
+  }
+
+  const normalizedToken = internalNormalizeBearerToken(input)
+  return normalizedToken.length === 0 ? undefined : normalizedToken
+}

package/src/credential/index.ts

@@ -0,0 +1,4 @@
+export * from "./api-key.ts"
+export * from "./password.ts"
+export * from "./json-web-token.ts"
+export * from "./bearer.ts"

package/src/credential/json-web-token.ts

@@ -0,0 +1,96 @@
+import { jwtVerify, SignJWT } from "jose"
+
+/**
+ * JSON Web Token（JWT）中当前对外承诺的业务载荷。
+ */
+export interface JsonWebTokenPayload {
+  userId: string
+}
+
+// JWT 的签发和校验都要求把共享密钥表示为字节序列。
+// 这个辅助函数明确说明：传入的密钥字符串会按 UTF-8 编码后再交给签名与验签逻辑。
+const internalJsonWebTokenTextToBytes = (text: string): Uint8Array => {
+  return new TextEncoder().encode(text)
+}
+
+// JWT 的过期时间既可以用持续时间字符串表示，也可以用相对秒数表示。
+// 这个辅助函数统一把 number 解释为“若干秒后过期”，避免把相对时长误当成绝对 Unix 时间。
+const internalNormalizeJsonWebTokenExpiresIn = (expiresIn: string | number): string | number => {
+  return typeof expiresIn === "number"
+    ? `${expiresIn}s`
+    : expiresIn
+}
+
+/**
+ * 创建 JsonWebToken 实例时需要提供的配置。
+ *
+ * `secret` 表示对称签名密钥，`expiresIn` 表示 token 的相对过期时间。
+ */
+export interface JsonWebTokenOptions {
+  secret: string
+  expiresIn: string | number
+}
+/**
+ * 提供围绕 JSON Web Token（JWT）进行签发与解析的基础能力。
+ *
+ * 当前实现使用对称密钥的 HS256 算法，并把 `userId` 作为默认业务载荷写入 token。
+ * `expiresIn` 表示相对时长：若传入字符串，可使用 `1h`、`30m` 之类的持续时间文本；若传入数字，则表示多少秒后过期。
+ *
+ * @example
+ * ```
+ * const jwt = new JsonWebToken({ secret: "secret", expiresIn: "1h" })
+ * const token = await jwt.signToken("user-1")
+ * // Expect: 3
+ * const example1 = token.split(".").length
+ * // Expect: "user-1"
+ * const example2 = await jwt.parseToken(token)
+ * ```
+ */
+export class JsonWebToken {
+  private options: JsonWebTokenOptions
+
+  constructor(options: JsonWebTokenOptions) {
+    this.options = options
+  }
+
+  /**
+   * 为给定用户标识签发 JWT 字符串。
+   */
+  async signToken(userId: string): Promise<string> {
+    const { secret, expiresIn } = this.options
+    return await new SignJWT({ userId } satisfies JsonWebTokenPayload)
+      .setProtectedHeader({ alg: "HS256", typ: "JWT" })
+      .setIssuedAt()
+      .setExpirationTime(internalNormalizeJsonWebTokenExpiresIn(expiresIn))
+      .sign(internalJsonWebTokenTextToBytes(secret))
+  }
+
+  /**
+   * 解析原始 JWT 字符串，并返回其中的用户标识。
+   */
+  async parseToken(token: string | undefined): Promise<string | undefined> {
+    if (token === undefined) {
+      return undefined
+    }
+
+    try {
+      const { secret } = this.options
+      const { payload } = await jwtVerify<JsonWebTokenPayload>(
+        token,
+        internalJsonWebTokenTextToBytes(secret),
+        {
+          algorithms: ["HS256"],
+        }
+      )
+
+      if (typeof payload.userId !== "string") {
+        return undefined
+      }
+
+      return payload.userId
+    }
+    catch {
+      return undefined
+    }
+  }
+}

package/src/credential/password.ts

@@ -0,0 +1,170 @@
+const internalPasswordPbkdf2IterationCount = 210_000
+const internalPasswordKeyLengthBits = 512
+const internalPasswordHexRegexp = /^[0-9A-F]+$/i
+
+// Password 的散列推导依赖 SubtleCrypto。
+// 这个辅助函数显式检查运行时能力，避免在不支持 PBKDF2 的环境里产生看似成功但实际不可用的结果。
+const internalGetSubtleCrypto = (): SubtleCrypto => {
+  if (globalThis.crypto === undefined || globalThis.crypto.subtle === undefined) {
+    throw new Error("Password utilities require crypto.subtle")
+  }
+
+  return globalThis.crypto.subtle
+}
+
+// Password 的盐值生成从随机字节开始。
+// 这个辅助函数同时负责长度校验和随机字节填充，让后续逻辑只需要处理已经生成好的安全随机输入。
+const internalPasswordGetRandomValues = (length: number): Uint8Array => {
+  if (Number.isInteger(length) === false || length <= 0) {
+    throw new RangeError(`Expected length to be a positive integer, got: ${length}`)
+  }
+
+  if (globalThis.crypto === undefined || typeof globalThis.crypto.getRandomValues !== "function") {
+    throw new Error("Credential utilities require crypto.getRandomValues")
+  }
+
+  const buffer = new Uint8Array(length)
+  globalThis.crypto.getRandomValues(buffer)
+  return buffer
+}
+
+// 十六进制文本是一种稳定、可打印、便于传输的字节表示方式。
+// 这个辅助函数会把每个字节编码成固定两位字符，保证相同字节长度总是得到相同文本长度。
+const internalPasswordBytesToHex = (bytes: Uint8Array): string => {
+  return Array.from(bytes, value => value.toString(16).padStart(2, "0")).join("")
+}
+
+// PBKDF2 接收的 salt 最终必须是原始字节序列。
+// 这个辅助函数会先校验十六进制文本是否合法，再按两位一组恢复成真实字节，避免把坏输入静默带入密码推导流程。
+const internalPasswordHexToBytes = (hex: string): Uint8Array => {
+  if (hex.length === 0 || hex.length % 2 !== 0 || internalPasswordHexRegexp.test(hex) === false) {
+    throw new TypeError(`Expected an even-length hexadecimal string, got: ${hex}`)
+  }
+
+  const bytes = new Uint8Array(hex.length / 2)
+
+  for (let index = 0; index < hex.length; index = index + 2) {
+    bytes[index / 2] = Number.parseInt(hex.slice(index, index + 2), 16)
+  }
+
+  return bytes
+}
+
+// Web Crypto 处理密码时接收的是字节而不是普通字符串。
+// 这个辅助函数负责使用 UTF-8 把文本密码编码成稳定字节序列，使同一段文本在相同环境下得到一致输入。
+const internalPasswordTextToBytes = (text: string): Uint8Array => {
+  return new TextEncoder().encode(text)
+}
+
+// 某些 Web Crypto 方法要求输入值是 ArrayBuffer。
+// 这个辅助函数会复制一份字节数据再取出 buffer，避免把原始视图的偏移量和切片状态带进底层 API。
+const internalPasswordBytesToArrayBuffer = (bytes: Uint8Array): ArrayBuffer => {
+  return Uint8Array.from(bytes).buffer
+}
+
+// 散列比较不能只依赖普通字符串相等判断。
+// 这个辅助函数会遍历完整字符串并累计差异，避免在第一个不同字符处提前返回而暴露可观察的比较差异。
+const internalPasswordSafeEqual = (left: string, right: string): boolean => {
+  if (left.length !== right.length) {
+    return false
+  }
+
+  let difference = 0
+
+  for (let index = 0; index < left.length; index = index + 1) {
+    const leftCodePoint = left.codePointAt(index) ?? 0
+    const rightCodePoint = right.codePointAt(index) ?? 0
+    difference = difference | (leftCodePoint ^ rightCodePoint)
+  }
+
+  return difference === 0
+}
+
+// Step 1: 校验盐值长度。
+//
+// `length` 表示盐值的字节数；由于结果会编码成十六进制文本，因此结果字符串长度始终是 `length * 2`。
+const internalAssertPasswordSaltLength = (length: number): void => {
+  if (Number.isInteger(length) === false || length <= 0) {
+    throw new RangeError(`Expected length to be a positive integer, got: ${length}`)
+  }
+}
+
+// Step 2: 生成十六进制盐值。
+//
+// 盐值先以随机字节形式生成，再编码成十六进制文本。
+// 这种表示方式既适合传输和存储，也能和后续 PBKDF2 所需的原始字节输入建立清楚的一一对应关系。
+const internalGeneratePasswordSalt = (length: number): string => {
+  internalAssertPasswordSaltLength(length)
+  return internalPasswordBytesToHex(internalPasswordGetRandomValues(length))
+}
+
+// Step 3: 用 PBKDF2-SHA-512 从“明文密码 + 盐值”导出稳定散列。
+//
+// 该过程先把密码编码成字节，再把十六进制盐值还原成字节，最后交给 Web Crypto 推导固定长度的散列结果。
+const internalDerivePasswordHash = async (password: string, salt: string): Promise<string> => {
+  const subtleCrypto = internalGetSubtleCrypto()
+  const importedKey = await subtleCrypto.importKey("raw", internalPasswordBytesToArrayBuffer(internalPasswordTextToBytes(password)), "PBKDF2", false, ["deriveBits"])
+  const derivedBits = await subtleCrypto.deriveBits({
+    name: "PBKDF2",
+    hash: "SHA-512",
+    salt: internalPasswordBytesToArrayBuffer(internalPasswordHexToBytes(salt)),
+    iterations: internalPasswordPbkdf2IterationCount,
+  }, importedKey, internalPasswordKeyLengthBits)
+
+  return internalPasswordBytesToHex(new Uint8Array(derivedBits))
+}
+
+/**
+ * 提供围绕密码盐值生成、带盐散列与比较的基础能力。
+ */
+export const Password = {
+  /**
+   * 生成指定字节长度的随机盐，并以十六进制字符串返回。
+   *
+   * @example
+   * ```
+   * const salt = Password.generateSalt(16)
+   * // Expect: 32
+   * const example1 = salt.length
+   * // Expect: true
+  * const example2 = /^[0-9A-F]+$/i.test(salt)
+   * ```
+   */
+  generateSalt(length: number): string {
+    return internalGeneratePasswordSalt(length)
+  },
+
+  /**
+   * 使用 PBKDF2-SHA-512 与盐值生成密码散列。
+   *
+   * @example
+   * ```
+  * const hash = await Password.hashPasswordWithSalt("secret", "00112233445566778899AABBCCDDEEFF")
+   * // Expect: 128
+   * const example1 = hash.length
+   * ```
+   */
+  async hashPasswordWithSalt(password: string, salt: string): Promise<string> {
+    return await internalDerivePasswordHash(password, salt)
+  },
+
+  /**
+   * 比较明文密码与既有散列是否匹配。
+   *
+   * @example
+   * ```
+  * const salt = "00112233445566778899AABBCCDDEEFF"
+   * const hash = await Password.hashPasswordWithSalt("secret", salt)
+   * // Expect: true
+   * const example1 = await Password.comparePassword("secret", hash, salt)
+   * // Expect: false
+   * const example2 = await Password.comparePassword("other", hash, salt)
+   * ```
+   */
+  async comparePassword(password: string, hashedPassword: string, salt: string): Promise<boolean> {
+    // 比较密码时不能直接比较明文，而是要先按同样规则重新计算散列。
+    // 固定时序比较可以减少在第一个不同字符处提前返回所带来的可观察差异。
+    const recalculatedHash = await internalDerivePasswordHash(password, salt)
+    return internalPasswordSafeEqual(recalculatedHash, hashedPassword)
+  },
+}

package/src/cron/README.md

@@ -0,0 +1,86 @@
+# Cron
+
+## Description
+
+Cron 模块提供围绕 Cron 表达式与计划触发时点计算的基础建模能力，用于在不执行具体任务的前提下稳定描述某个计划何时匹配、何时已经触发以及何时将要触发。
+
+它关注的是“计划语义如何被抽象为稳定模型”，而不是把某个运行时里的定时任务 API 直接包一层后暴露出去。对于使用者而言，这个模块更适合承载计划匹配、运行点推导与计划边界判断，而不是任务执行、副作用调度或分布式作业管理。
+
+## For Understanding
+
+理解 Cron 模块时，重点应放在“一个计划本身如何被表达与判断”，而不是“某段任务代码何时被调度执行”。Cron 在这里表达的是一种时间计划模型：给定某个计划模式后，外部可以稳定地询问它是否匹配某个时间点、它最近一次计划运行点是什么、以及未来的计划运行点是什么。
+
+因此，这个模块适合放在以下边界中：
+
+- 你需要复用一类与计划时点推导相关的基础能力，而不想在业务代码里反复处理 Cron 表达式解析与时间匹配。
+- 你需要把“计划何时成立”与“计划成立后业务要做什么”明确分离，让上层自行决定副作用。
+- 你需要一个环境中立的计划模型，以便在不同运行时或不同任务系统之间复用相同的计划语义。
+
+同时也要守住几个边界：
+
+- Cron 模块不负责执行任务，也不负责重试、并发控制、分布式锁、任务持久化或调度生命周期管理。
+- 某个能力如果主要表达的是“任务如何运行”，通常更适合放在调度器、作业系统或编排模块中，而不是放在 Cron 模块中。
+- 如果某种时间逻辑不以 Cron 计划语义为中心，而更偏向广义时间状态或过期管理，则通常应放在其它时间相关模块边界内理解。
+
+## For Using
+
+当你已经明确需要的是“计划时点模型”，而不是一个直接帮你启动任务的执行器时，可以接入 Cron 模块。它更适合被用来完成三类工作：一类是定义一个长期可复用的计划模式；一类是围绕该计划推导过去、当前与未来的运行点；另一类是判断某个给定时点是否满足该计划。
+
+在实际接入时，更合理的方式是把它视为上层调度逻辑的基础判断器。业务系统、任务系统或编排系统可以依赖这里提供的计划语义来决定何时启动、跳过、补偿或展示某个任务，但这些决策本身不应内置在 Cron 模块里。
+
+如果你的需求已经超出了“计划表达与时点判断”，例如需要内建回调执行、失败重试、任务注册表或长期运行的后台调度循环，那么应当在更上层的模块中组合这个计划模型，而不是把这些职责继续压进 Cron 模块。
+
+## For Contributing
+
+贡献 Cron 模块时，应优先确认新增内容表达的是不是稳定的计划语义，而不是某个调度实现中的临时便利逻辑。这里的核心问题始终是：某种能力是否仍然围绕 Cron 计划本身展开，还是已经开始转向任务执行与调度控制。如果是后者，就不应继续塞进这个模块。
+
+扩展时尤其要避免两类偏差。一类是把 Cron 模块做成“带回调的任务执行器”，让它逐步承担不属于计划模型的职责；另一类是为了方便而把底层解析器的细碎内部能力直接公开，导致外部接入依赖不稳定的内部结构。更稳妥的做法，是围绕计划模式、计划匹配和计划运行点这些稳定语义组织公共 API，并把解析器适配细节保持在内部。
+
+### JSDoc 注释格式要求
+
+- 每个公开导出的目标（类型、函数、变量、类等）都应包含 JSDoc 注释，让人在不跳转实现的情况下就能理解用途。
+- JSDoc 注释第一行应为清晰且简洁的描述，该描述优先使用中文（英文也可以）。
+- 如果描述后还有其他内容，应在描述后加一个空行。
+- 如果有示例，应使用 `@example` 标签，后接三重反引号代码块（不带语言标识）。
+- 如果有示例，应包含多个场景，展示不同用法，尤其要覆盖常见组合方式或边界输入。
+- 如果有示例，应使用注释格式说明每个场景：`// Expect: <result>`。
+- 如果有示例，应将结果赋值给 `example1`、`example2` 之类的变量，以保持示例易读。
+- 如果有示例，`// Expect: <result>` 应该位于 `example1`、`example2` 之前，以保持示例的逻辑清晰。
+- 如果有示例，应优先使用确定性示例；避免断言精确的随机输出。
+- 如果函数返回结构化字符串，应展示其预期格式特征。
+- 如果有参考资料，应将 `@see` 放在 `@example` 代码块之后，并用一个空行分隔。
+
+### 实现规范要求
+
+- 不同程序元素之间使用一个空行分隔，保持结构清楚。这里的程序元素，通常指函数、类型、常量，以及直接服务于它们的辅助元素。
+- 某程序元素独占的辅助元素与该程序元素本身视为一个整体，不要在它们之间添加空行。
+- 程序元素的辅助元素应该放置在该程序元素的上方，以保持阅读时的逻辑顺序。
+- 若辅助元素被多个程序元素共享，则应将其视为独立的程序元素，放在这些程序元素中第一个相关目标的上方，并与后续程序元素之间保留一个空行。
+- 辅助元素也应该像其它程序元素一样，保持清晰的命名和适当的注释，以便在需要阅读实现细节时能够快速理解它们的作用和使用方式。
+- 辅助元素的命名必须以前缀 `internal` 开头（或 `Internal`，大小写不敏感）。
+- 辅助元素永远不要公开导出。
+- 被模块内多个不同文件中的程序元素共享的辅助元素，应该放在一个单独的文件中，例如 `./src/cron/internal.ts`。
+- 模块内可以包含子模块。只有当某个子目录表达一个稳定、可单独理解、且可能被父模块重导出的子问题域时，才应将其视为子模块。
+- 子模块包含多个文件时，应该为其单独创建子文件夹，并为其创建单独的 Barrel 文件；父模块的 Barrel 文件再重导出子模块的 Barrel 文件。
+- 子模块不需要有自己的 `README.md`。
+- 子模块可以有自己的 `internal.ts` 文件，多个子模块共享的辅助元素应该放在父模块的 `internal.ts` 文件中，单个子模块共享的辅助元素应该放在该子模块的 `internal.ts` 文件中。
+- 对模块依赖关系的要求（通常是不循环依赖或不反向依赖）与对 DRY 的要求可能产生冲突。此时，若复用的代码数量不大，可以适当牺牲 DRY，复制粘贴并保留必要的注释说明；若复用的代码数量较大，则可以将其抽象到新的文件或子模块中，如 `common.ts`，并在需要的地方导入使用。
+- 与 Cron 相关的实现应优先围绕计划语义、计划匹配与计划运行点组织，避免把任务执行、副作用调度或运行时专属控制逻辑直接提升为 Cron 的长期公共语义。
+
+### 导出策略要求
+
+- 保持内部辅助项和内部符号为私有，不要让外部接入依赖临时性的内部结构。
+- 每个模块都应有一个用于重导出所有公共 API 的 Barrel 文件。
+- Barrel 文件应命名为 `index.ts`，放在模块目录根部，并且所有公共 API 都应从该文件导出。
+- 新增公共能力时，应优先检查它是否表达稳定、清楚且值得长期维护的计划语义，而不是某段实现细节的便捷暴露；仅在确认需要长期对外承诺时再加入 Barrel 导出。
+
+### 测试要求
+
+- 若程序元素是函数，则只为该函数编写一个测试，如果该函数需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，则至少要为该类的每一个方法编写一个测试，如果该方法需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，除了为该类的每一个方法编写至少一个测试之外，还可以为该类编写任意多个测试，以覆盖该类的不同使用场景或边界情况。
+- 若编写测试时需要用到辅助元素（Mock 或 Spy 等），可以在测试文件中直接定义这些辅助元素。若辅助元素较为简单，则可以直接放在每一个测试内部，优先保证每个测试的独立性，而不是追求极致 DRY；若辅助元素较为复杂或需要在多个测试中复用，则可以放在测试文件顶部，供该测试文件中的所有测试使用。
+- 测试顺序应与源文件中被测试目标的原始顺序保持一致。
+- 若该模块不需要测试，必须在说明文件中明确说明该模块不需要测试，并说明理由。一般来说，只有在该模块没有可执行的公共函数、只承载类型层表达，或其语义已被上层模块的测试完整覆盖且重复测试几乎不再带来额外价值时，才适合这样处理。
+- 模块的单元测试文件目录是 `./tests/unit/cron`。
+- 对 Cron 相关能力，应优先覆盖计划参数传递、过去与未来运行点推导、空结果规范化以及时间匹配判断等场景。

package/src/cron/cron.ts

@@ -0,0 +1,87 @@
+import { Cron as CronerCron } from "croner"
+
+/**
+ * Cron 计划模型的配置项。
+ */
+export interface CronOptions {
+  /**
+   * 用于描述计划的 Cron 表达式或单次触发时点。
+   */
+  pattern: string | Date
+
+  /**
+   * @default false
+   */
+  domAndDow?: boolean | undefined
+}
+
+/**
+ * 用于围绕 Cron 计划计算运行时点并判断时间匹配关系的模型。
+ */
+export class Cron {
+  protected options: CronOptions
+  protected croner: CronerCron
+
+  /**
+   * 使用给定配置创建一个 Cron 计划模型。
+   */
+  constructor(options: CronOptions) {
+    this.options = options
+    this.croner = new CronerCron(options.pattern, {
+      domAndDow: options.domAndDow ?? false,
+      alternativeWeekdays: false,
+    })
+  }
+
+  /**
+   * 获取该计划最近一次运行时点。
+   */
+  prevRun(): Date | undefined {
+    const prev = this.croner.previousRun()
+    return prev === null ? undefined : prev
+  }
+
+  /**
+   * 获取该计划最近若干次运行时点。
+   */
+  prevRuns(n: number): Date[] {
+    const prevRuns = this.croner.previousRuns(n)
+    return prevRuns
+  }
+
+  /**
+   * 获取该计划当前运行时点。
+   */
+  currentRun(): Date | undefined {
+    const current = this.croner.currentRun()
+    return current === null ? undefined : current
+  }
+
+  /**
+   * 获取该计划下一次运行时点。
+   */
+  nextRun(): Date | undefined {
+    const next = this.croner.nextRun()
+    return next === null ? undefined : next
+  }
+
+  /**
+   * 获取该计划接下来若干次运行时点。
+   */
+  nextRuns(n: number): Date[] {
+    const nextRuns = this.croner.nextRuns(n)
+    return nextRuns
+  }
+
+  /**
+   * 判断给定时间点是否匹配该计划。
+   */
+  match(date: Date): boolean {
+    const isMatch = this.croner.match(date)
+    return isMatch
+  }
+}
+
+export const isCron = (value: unknown): value is Cron => {
+  return value instanceof Cron
+}

package/src/cron/index.ts

@@ -0,0 +1 @@
+export * from "./cron.ts"