@planet-matrix/mobius-model 0.3.0 → 0.5.0

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