@planet-matrix/mobius-model 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planet-matrix/mobius-model",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Mobius model.",
   "keywords": [
     "mobius",

package/src/basic/README.md

@@ -9,22 +9,23 @@ This module provides runtime utilities organized by domain so you can quickly lo
 ### 1. Domain Areas
 
 1. Helper: Shared runtime helpers used across other domains.
-2. Is: Predicates and type guards for runtime checks.
-3. String: String manipulation, slicing, and formatting helpers.
-4. Number: Numeric checks, parsing, and math-oriented helpers.
-5. Boolean: Boolean helpers and predicates.
-6. BigInt: BigInt checks and helpers.
-7. Symbol: Symbol checks and helpers.
-8. Array: Array construction, slicing, and transformation helpers.
-9. Object: Object predicates and object utility helpers.
-10. Function: Function predicates and invocation-related helpers.
-11. Temporal: Temporal/date-time predicates and helpers.
-12. Error: Error predicates and helpers.
-13. RegExp: RegExp predicates and helpers.
-14. Promise: Promise predicates and async-related helpers.
-15. Stream: Stream predicates and stream-related helpers.
-
-For a full list of exports, see the domain files (Is, String, Number, Temporal, Promise, Stream, etc.).
+2. Is: Runtime predicates and type guards (primitives, objects, iterables, DOM/browser targets, and more).
+3. String: String generation, casing conversion, slicing, splitting, and truncation helpers.
+4. Number: Numeric normalization, range constraint, parity checks, and randomization helpers.
+5. Boolean: Boolean conversion and logical operation helpers.
+6. BigInt: BigInt-oriented helpers.
+7. Symbol: Symbol creation, inspection, and conversion helpers.
+8. Array: Array-oriented helpers and transformations.
+9. Object: Object field selection/exclusion, Date-field timestamp conversion, and object utility helpers.
+10. Function: Function composition and execution-control helpers (once, debounce, throttle, memoize, etc.).
+11. Temporal: Date/time formatting, relative-time, and humanization helpers.
+12. Error: Error detection and exception-stringify helpers.
+13. RegExp: RegExp-based validation helpers.
+14. Promise: Promise control-flow, queueing, retry, interval, and forever-loop helpers.
+15. Stream: ReadableStream construction, consumption, and transform helpers.
+16. Enhance: Runtime enhancement helpers (for example, BigInt JSON serialization support).
+
+For a full list of exports, see the domain files (Helper, Is, String, Number, Boolean, BigInt, Symbol, Array, Object, Function, Temporal, Error, RegExp, Promise, Stream, Enhance).
 
 ## For Contributors
 

package/src/basic/enhance.ts

@@ -0,0 +1,10 @@
+/**
+ * @see {@link https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/BigInt#%E5%9C%A8_json_%E4%B8%AD%E4%BD%BF%E7%94%A8}
+ */
+export const enhanceBigInt = (): void => {
+  // @ts-expect-error - extend BigInt toJSON
+  // oxlint-disable-next-line no-extend-native
+  BigInt.prototype.toJSON = function toJSON(): number {
+    return Number(this.toString())
+  }
+}

package/src/basic/index.ts

@@ -13,3 +13,5 @@ export * from "./error.ts"
 export * from "./regexp.ts"
 export * from "./promise.ts"
 export * from "./stream.ts"
+
+export * from "./enhance.ts"

package/src/basic/object.ts

@@ -1,4 +1,5 @@
 import type { AnyRecord } from "../type/index.ts"
+import { isDate } from "./is.ts"
 
 /**
  * Return a new object that includes only the specified keys from the source object.
@@ -56,3 +57,84 @@ export const excludeFields = <T extends AnyRecord, K extends keyof T>(
   // oxlint-disable-next-line no-unsafe-type-assertion
   return newObject as Omit<T, K> // 使用Omit类型确保返回的类型反映了被排除的键
 }
+
+/**
+ * Convert all Date fields in an object to number.
+ *
+ * @example
+ * ```before
+ * type Obj = {
+ *   createdAt: Date,
+ * }
+ * ```
+ * ```after
+ * type Obj = {
+ *   createdAt: number,
+ * }
+ * ```
+ *
+ * @example
+ * ```before
+ * type Obj = {
+ *   createdAt: Date | undefined,
+ * }
+ * ```
+ * ```after
+ * type Obj = {
+ *   createdAt: number | undefined,
+ * }
+ * ```
+ *
+ * @example
+ * ```before
+ * type Obj = {
+ *   createdAt: Date | null,
+ * }
+ * ```
+ * ```after
+ * type Obj = {
+ *   createdAt: number | null,
+ * }
+ * ```
+ */
+export type ObjectDateFieldsToNumber<O extends object> = {
+  [K in keyof O]: O[K] extends Date
+  ? number
+  : (
+    O[K] extends Date | undefined
+    ? number | undefined
+    :
+    (O[K] extends Date | null
+      ? number | null
+      : (
+        O[K] extends object
+        ? ObjectDateFieldsToNumber<O[K]>
+        : O[K]
+      )
+    )
+  )
+}
+/**
+ * Convert all Date fields in an object to number.
+ *
+ * @example
+ * ```
+ * const obj = { createdAt: new Date() };
+ * const result = objectDateFieldsToNumber(obj);
+ * // Expect: { createdAt: 1712345678901 }
+ * ```
+ */
+export const objectDateFieldsToNumber = <O extends Record<string | number | symbol, unknown>>(
+  obj: O
+): ObjectDateFieldsToNumber<O> => {
+  // oxlint-disable-next-line guard-for-in
+  for (const key in obj) {
+    const value = obj[key];
+    if (isDate(value)) {
+      // oxlint-disable-next-line no-unsafe-type-assertion
+      obj[key] = value.getTime() as O[Extract<keyof O, string>]
+    }
+  }
+  // oxlint-disable-next-line no-unsafe-type-assertion
+  return obj as ObjectDateFieldsToNumber<O>
+}

package/src/encoding/README.md

@@ -0,0 +1,105 @@
+# Encoding
+
+Runtime utilities for encoding and decoding text. This module currently focuses on Base64 conversions with predictable UTF-8 behavior.
+
+## For Users
+
+This module provides lightweight encoding helpers for common text <-> Base64 scenarios.
+
+### 1. Domain Areas
+
+1. Base64: Convert UTF-8 strings to Base64, decode Base64 back to UTF-8 strings, and validate Base64 input.
+
+Current public exports:
+
+- `isBase64(input: string): boolean`
+- `assertBase64(input: string): void`
+- `stringToBase64(input: string): string`
+- `base64ToString(input: string): string`
+
+## For Contributors
+
+This guide documents conventions and best practices for implementing encoding utilities in this module.
+
+### 1. Documentation and Comments
+
+#### 1.1 JSDoc Comment Format
+
+Every exported function should include JSDoc in this form:
+
+```typescript
+/**
+ * Brief one-line description of what the function does.
+ *
+ * @example
+ * ```
+ * // Expect: "aGVsbG8="
+ * const example1 = stringToBase64("hello")
+ * // Expect: "hello"
+ * const example2 = base64ToString("aGVsbG8=")
+ * ```
+ */
+export const stringToBase64 = (input: string): string => {
+	...
+}
+```
+
+**Documentation Rules:**
+- First line: Clear, concise description starting with a verb (Check, Get, Convert, etc.)
+- Add a blank line after the description
+- Use `@example` tag followed by triple backticks
+- Include multiple cases showing different scenarios
+- Use comment format: `// Expect: <result>`
+- Assign example results to variables like `example1`, `example2` to keep examples readable
+- Place `@see`(if has) after the `@example` block, separated by a blank line
+- Prefer deterministic examples; avoid randomness or time-dependent output in docs
+- If a function returns a non-scalar, show the expected shape or key properties
+
+### 2. Runtime Implementation Patterns
+
+#### 2.1 Input and Output Rules
+
+- Text conversion utilities should accept explicit `string` input.
+- Behavior should be deterministic and side-effect free.
+- Keep UTF-8 semantics explicit in implementation.
+
+#### 2.2 Helper Placement
+
+- Place local helper constants/functions immediately before the utility they support.
+- Prefix non-exported helpers with `internal`.
+- Never export internal helpers.
+
+#### 2.3 Spacing
+
+- Separate different utility functions with a single blank line.
+
+### 3. Naming Conventions
+
+#### 3.1 Function Name Format
+
+Use clear operation-oriented names in the `encoding` domain:
+
+- `isBase64` for Base64 validation checks returning boolean
+- `assertBase64` for Base64 validation that throws on malformed input
+- `stringToBase64` for UTF-8 string to Base64 conversion
+- `base64ToString` for Base64 to UTF-8 string conversion
+
+Prefer names that encode both source and target representations.
+
+### 4. Export Strategy
+
+- Export all public utilities from domain files.
+- Re-export them through `index.ts`.
+- Do not export internal helpers.
+
+### 5. Common Pitfalls to Avoid
+
+1. Do not assume all Base64 input is valid without documenting behavior.
+2. Do not mix encodings implicitly (keep UTF-8 explicit).
+3. Do not add environment-specific APIs unless compatibility is documented.
+4. Do not mutate shared state.
+
+### 6. Testing Requirements
+
+- Write one test per function.
+- If multiple cases are needed, include them within the same test.

package/src/encoding/base64.ts

@@ -0,0 +1,98 @@
+const internalBase64Pattern = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/
+const internalNormalizeBase64 = (input: string): string => {
+  return input.replaceAll(/\s+/g, "")
+}
+/**
+ * Check whether input is a valid Base64 string.
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = isBase64("aGVsbG8=")
+ * // Expect: false
+ * const example2 = isBase64("abc")
+ * ```
+ */
+export const isBase64 = (input: string): boolean => {
+  const normalizedInput = internalNormalizeBase64(input)
+  return internalBase64Pattern.test(normalizedInput)
+}
+
+const internalAssertValidBase64 = (input: string): void => {
+  if (internalBase64Pattern.test(input) === false) {
+    throw new TypeError("Invalid Base64 input")
+  }
+}
+/**
+ * Assert input is a valid Base64 string.
+ *
+ * @throws {TypeError} when input is not valid Base64
+ */
+export const assertBase64 = (input: string): void => {
+  const normalizedInput = internalNormalizeBase64(input)
+  internalAssertValidBase64(normalizedInput)
+}
+
+const internalStringToBase64ByBrowserApi = (input: string): string => {
+  const bytes = new TextEncoder().encode(input)
+  let binaryString = ""
+
+  bytes.forEach((byte) => {
+    binaryString = binaryString + String.fromCodePoint(byte)
+  })
+
+  return btoa(binaryString)
+}
+/**
+ * Convert a UTF-8 string into a Base64 string.
+ *
+ * @example
+ * ```
+ * // Expect: "aGVsbG8="
+ * const example1 = stringToBase64("hello")
+ * // Expect: "5L2g5aW9"
+ * const example2 = stringToBase64("你好")
+ * ```
+ */
+export const stringToBase64 = (input: string): string => {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(input, "utf8").toString("base64")
+  }
+
+  if (typeof btoa !== "undefined") {
+    return internalStringToBase64ByBrowserApi(input)
+  }
+
+  throw new Error("No Base64 runtime support found")
+}
+
+const internalBase64ToStringByBrowserApi = (input: string): string => {
+  const binaryString = atob(input)
+  const bytes = Uint8Array.from(binaryString, char => char.codePointAt(0) ?? 0)
+  return new TextDecoder().decode(bytes)
+}
+/**
+ * Convert a valid Base64 string into a UTF-8 string.
+ *
+ * @example
+ * ```
+ * // Expect: "hello"
+ * const example1 = base64ToString("aGVsbG8=")
+ * // Expect: "你好"
+ * const example2 = base64ToString("5L2g5aW9")
+ * ```
+ */
+export const base64ToString = (input: string): string => {
+  const normalizedInput = internalNormalizeBase64(input)
+  internalAssertValidBase64(normalizedInput)
+
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(normalizedInput, "base64").toString("utf8")
+  }
+
+  if (typeof atob !== "undefined") {
+    return internalBase64ToStringByBrowserApi(normalizedInput)
+  }
+
+  throw new Error("No Base64 runtime support found")
+}

package/src/encoding/index.ts

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

package/src/index.ts

@@ -1,3 +1,5 @@
 export * as Basic from "./basic/index.ts"
 export * as Type from "./type/index.ts"
 export * as Reactor from "./reactor/index.ts"
+export * as Encoding from "./encoding/index.ts"
+export * as Random from "./random/index.ts"

package/src/random/README.md

@@ -0,0 +1,109 @@
+# Random
+
+Runtime utilities for generating random-oriented values with cross-runtime compatibility. This module currently focuses on UUID generation.
+
+## For Users
+
+This module provides lightweight helpers for random value generation scenarios.
+
+### 1. Domain Areas
+
+1. UUID: Generate RFC 4122 version-4 UUID strings with runtime-aware fallback behavior.
+
+Current public exports:
+
+- `isUuid(input: string): boolean`
+- `assertUuid(input: string): void`
+- `getUuidVersion(input: string): number`
+- `generateUuid(): string`
+
+## For Contributors
+
+This guide documents conventions and best practices for implementing random utilities in this module.
+
+### 1. Documentation and Comments
+
+#### 1.1 JSDoc Comment Format
+
+Every exported function should include JSDoc in this form:
+
+```typescript
+/**
+ * Brief one-line description of what the function does.
+ *
+ * @example
+ * ```
+ * const example1 = generateUuid()
+ * // Expect: true
+ * const example2 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(example1)
+ * ```
+ */
+export const generateUuid = (): string => {
+	...
+}
+```
+
+**Documentation Rules:**
+- First line: Clear, concise description starting with a verb (Generate, Check, Convert, etc.)
+- Add a blank line after the description
+- Use `@example` tag followed by triple backticks
+- Include multiple cases showing different scenarios
+- Use comment format: `// Expect: <result>`
+- Assign example results to variables like `example1`, `example2` to keep examples readable
+- Place `@see`(if has) after the `@example` block, separated by a blank line
+- Prefer deterministic examples; avoid asserting exact random outputs
+- If a function returns a structured string, show expected format characteristics
+
+### 2. Runtime Implementation Patterns
+
+#### 2.1 Compatibility First
+
+- Prefer standard runtime APIs when available (for example, `crypto.randomUUID`).
+- Keep fallback logic for environments where modern APIs are unavailable.
+
+#### 2.2 Deterministic Interface
+
+- Public API shape should remain deterministic even if output values are random.
+- Return values should always conform to the documented output format.
+
+#### 2.3 Helper Placement
+
+- Place local helper constants/functions immediately before the utility they support.
+- Prefix non-exported helpers with `internal`.
+- Never export internal helpers.
+
+#### 2.4 Spacing
+
+- Separate different utility functions with a single blank line.
+
+### 3. Naming Conventions
+
+#### 3.1 Function Name Format
+
+Use clear operation-oriented names in the `random` domain:
+
+- `isUuid` for UUID format validation checks
+- `assertUuid` for UUID validation that throws on malformed input
+- `getUuidVersion` for extracting UUID version numbers
+- `generateUuid` for UUID creation helpers
+
+Prefer names that clearly indicate output format and intent.
+
+### 4. Export Strategy
+
+- Export all public utilities from domain files.
+- Re-export them through `index.ts`.
+- Do not export internal helpers.
+
+### 5. Common Pitfalls to Avoid
+
+1. Do not assume browser-only APIs are always available.
+2. Do not couple random utilities to a specific runtime unless documented.
+3. Do not assert exact random results in tests.
+4. Do not mutate shared/global state permanently.
+
+### 6. Testing Requirements
+
+- Write one test per function.
+- If multiple cases are needed, include them within the same test.
+- For random outputs, validate shape/constraints instead of exact value.

package/src/random/index.ts

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

package/src/random/uuid.ts

@@ -0,0 +1,103 @@
+
+const internalUUID_REGEXP = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+/**
+ * Check whether input is a valid UUID string.
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = isUuid("550e8400-e29b-41d4-a716-446655440000")
+ * // Expect: false
+ * const example2 = isUuid("not-a-uuid")
+ * ```
+ */
+export const isUuid = (input: string): boolean => {
+  return internalUUID_REGEXP.test(input)
+}
+
+/**
+ * Assert input is a valid UUID string.
+ *
+ * @example
+ * ```
+ * // Expect: no throw
+ * const example1 = assertUuid("550e8400-e29b-41d4-a716-446655440000")
+ * // Expect: throws TypeError
+ * const example2 = () => assertUuid("not-a-uuid")
+ * ```
+ *
+ * @throws {TypeError} when input is not a valid UUID
+ */
+export const assertUuid = (input: string): void => {
+  if (isUuid(input) === false) {
+    throw new TypeError(`Expected a valid UUID string, got: ${input}`)
+  }
+}
+
+/**
+ * Get the version number from a valid UUID string.
+ *
+ * @example
+ * ```
+ * // Expect: 4
+ * const example1 = getUuidVersion("550e8400-e29b-41d4-a716-446655440000")
+ * // Expect: 1
+ * const example2 = getUuidVersion("123e4567-e89b-12d3-a456-426614174000")
+ * ```
+ *
+ * @throws {TypeError} when input is not a valid UUID
+ */
+export const getUuidVersion = (input: string): number => {
+  // 1) Ensure the input is a syntactically valid UUID string.
+  //    If invalid, assertUuid throws TypeError and prevents unsafe parsing.
+  assertUuid(input)
+
+  // 2) Per UUID canonical format xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx,
+  //    the version nibble is the first hex digit of the 3rd group.
+  //    In a 36-char UUID string, that position is index 14.
+
+  // 3) Convert the single hex character (for example "4") to a base-10 number.
+  //    parseInt("4", 16) -> 4, parseInt("a", 16) -> 10.
+  return Number.parseInt(input[14]!, 16)
+}
+
+/**
+ * Generate a RFC 4122 version-4 UUID string.
+ *
+ * @example
+ * ```
+ * const example1 = generateUuid()
+ * // Expect: true
+ * const example2 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(example1)
+ * ```
+ */
+export const generateUuid = (): string => {
+  if (typeof crypto === "object") {
+    if (typeof crypto.randomUUID === "function") {
+      return crypto.randomUUID()
+    }
+
+    if (typeof crypto.getRandomValues === "function" && typeof Uint8Array === "function") {
+      const buffer = new Uint8Array(16)
+      crypto.getRandomValues(buffer)
+
+      // Per RFC 4122, set bits for version and `clock_seq_hi_and_reserved`
+      buffer[6] = (buffer[6]! & 0x0F) | 0x40 // version 4
+      buffer[8] = (buffer[8]! & 0x3F) | 0x80 // variant 1
+
+      // Convert buffer to UUID string format
+      const hex = [...buffer].map(b => b.toString(16).padStart(2, "0")).join("")
+      return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`
+    }
+  }
+
+  // Fallback for environments without crypto support
+  const fallbackUUID = (): string => {
+    const random = (a: number): string => {
+      return ((a ^ ((Math.random() * 16) >> (a / 4))) & 15).toString(16)
+    }
+    return "10000000-1000-4000-8000-100000000000".replaceAll(/[018]/g, (char: string) => random(Number(char)))
+  }
+
+  return fallbackUUID()
+}

package/tests/unit/basic/object.spec.ts

@@ -1,6 +1,6 @@
 import { expect, test } from "vitest"
 
-import { excludeFields, includeFields } from "#Source/basic/object.ts"
+import { excludeFields, includeFields, objectDateFieldsToNumber } from "#Source/basic/object.ts"
 
 test("includeFields picks specified keys", () => {
   expect(includeFields({ a: 1, b: 2, c: 3 }, ["a", "c"])).toEqual({ a: 1, c: 3 })
@@ -13,3 +13,34 @@ test("excludeFields omits specified keys", () => {
   // @ts-expect-error - Testing behavior with undefined input
   expect(excludeFields(undefined, ["a"])).toEqual({})
 })
+
+test("objectDateFieldsToNumber converts top-level Date fields", () => {
+  const createdAt = new Date("2024-01-02T03:04:05.678Z")
+  const updatedAt = new Date("2024-02-03T04:05:06.789Z")
+  const nestedDate = new Date("2024-03-04T05:06:07.890Z")
+
+  const source = {
+    id: "x-1",
+    createdAt,
+    updatedAt,
+    nested: {
+      occurredAt: nestedDate,
+    },
+    optional: undefined as Date | undefined,
+    nullable: null as Date | null,
+  }
+
+  const result = objectDateFieldsToNumber(source)
+
+  expect(result).toEqual({
+    id: "x-1",
+    createdAt: createdAt.getTime(),
+    updatedAt: updatedAt.getTime(),
+    nested: {
+      occurredAt: nestedDate,
+    },
+    optional: undefined,
+    nullable: null,
+  })
+  expect(result).toBe(source)
+})

package/tests/unit/encoding/base64.spec.ts

@@ -0,0 +1,40 @@
+import { expect, test } from "vitest"
+
+import {
+  assertBase64,
+  base64ToString,
+  isBase64,
+  stringToBase64,
+} from "#Source/encoding/index.ts"
+
+test("isBase64 validates Base64 input", () => {
+  expect(isBase64("aGVsbG8=")).toBe(true)
+  expect(isBase64("5L2g5aW9")).toBe(true)
+  expect(isBase64("8J+Ri/CfjI0=")).toBe(true)
+  expect(isBase64("aGVs\n bG8=")).toBe(true)
+
+  expect(isBase64("%%%")).toBe(false)
+  expect(isBase64("abc")).toBe(false)
+})
+
+test("assertBase64 throws on malformed input", () => {
+  expect(() => assertBase64("aGVsbG8=")).not.toThrow()
+  expect(() => assertBase64("aGVs\n bG8=")).not.toThrow()
+  expect(() => assertBase64("%%%")).toThrow(TypeError)
+  expect(() => assertBase64("abc")).toThrow(TypeError)
+})
+
+test("stringToBase64 converts UTF-8 text to Base64", () => {
+  expect(stringToBase64("hello")).toBe("aGVsbG8=")
+  expect(stringToBase64("你好")).toBe("5L2g5aW9")
+  expect(stringToBase64("👋🌍")).toBe("8J+Ri/CfjI0=")
+})
+
+test("base64ToString converts Base64 to UTF-8 text and validates malformed input", () => {
+  expect(base64ToString("aGVsbG8=")).toBe("hello")
+  expect(base64ToString("5L2g5aW9")).toBe("你好")
+  expect(base64ToString("8J+Ri/CfjI0=")).toBe("👋🌍")
+
+  expect(() => base64ToString("%%%")).toThrow(TypeError)
+  expect(() => base64ToString("abc")).toThrow(TypeError)
+})