@planet-matrix/mobius-model 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planet-matrix/mobius-model",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Mobius model.",
   "keywords": [
     "mobius",
@@ -60,10 +60,10 @@
   },
   "dependencies": {},
   "devDependencies": {
-    "@planet-matrix/mobius-mono": "0.6.0",
+    "@planet-matrix/mobius-mono": "0.7.0",
     "@types/bun": "^1.3.8",
     "oxlint": "^1.42.0",
-    "oxlint-tsgolint": "^0.11.4",
+    "oxlint-tsgolint": "^0.13.0",
     "typescript": "^5.9.3",
     "@typescript/native-preview": "^7.0.0-dev.20260130.1",
     "vite": "^7.3.1",

package/scripts/build.ts

@@ -4,8 +4,8 @@ import { $, build } from "bun"
 console.log("Cleaning and preparing ./dist directory...")
 await $`rm -rf dist`
 
-console.log("Building TypeScript declarations...")
-await $`bun run tsgo --noEmit false`
+// console.log("Building TypeScript declarations...")
+// await $`bun run tsgo --noEmit false`
 
 console.log("Building the library with Bun...")
 const builtOutput = await build({
@@ -36,8 +36,8 @@ const builtOutput = await build({
   outdir: "./dist",
   packages: "bundle",
   plugins: [],
-  publicPath: undefined,
-  root: undefined,
+  // publicPath: undefined,
+  // root: undefined,
   sourcemap: "linked",
   splitting: true,
   target: "bun",

package/src/basic/README.md

@@ -0,0 +1,144 @@
+# Basic
+
+Runtime utilities for JavaScript primitives and built-in objects. This module focuses on safe, predictable helpers and type guards that you can use in everyday code.
+
+## For Users
+
+This module provides runtime utilities organized by domain so you can quickly locate the right tool for a specific problem.
+
+### 1. Domain Areas
+
+1. Helper: Shared runtime helpers used across other domains.
+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
+
+This guide documents the conventions and best practices for implementing runtime utilities in this module. All implementations should follow these patterns for consistency and maintainability.
+
+### 1. Documentation and Comments
+
+#### 1.1 JSDoc Comment Format
+
+Every exported function should have a JSDoc comment following this structure:
+
+```typescript
+/**
+ * Brief one-line description of what the function does.
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = isString("hello")
+ * // Expect: false
+ * const example2 = isString(123)
+ * ```
+ * 
+ * @see {@link https://……}
+ */
+export const isString = (value: unknown): value is 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 Prefer Type Predicates
+
+Use type predicates for validation functions to maximize type safety:
+
+```typescript
+export const isDate = (value: unknown): value is Date => {
+	return Object.prototype.toString.call(value) === "[object Date]"
+}
+```
+
+#### 2.2 Accept `unknown`
+
+Public utilities should accept `unknown` unless there is a strong reason to require a narrower input type.
+
+#### 2.3 Avoid Side Effects
+
+Helpers should be deterministic and should not mutate input values unless explicitly documented.
+
+#### 2.4 Helper Placement
+
+- If a utility function uses helper variables or helper functions, place those helpers immediately before the utility function.
+- Do not add blank lines between a helper and the utility function it supports.
+- Helper variables and functions must be prefixed with `internal`.
+- Helper variables and functions must never be exported.
+
+#### 2.5 Spacing
+
+- Separate different utility functions with a single blank line.
+
+### 3. Naming Conventions
+
+#### 3.1 Function Name Format
+
+All functions should follow a consistent naming pattern:
+
+**Format:** `<domain><Operation><Qualifier>`
+
+- `is*` for predicates and checks (for example, `isPlainObject`, `isFiniteNumber`)
+- `string*` for string utilities (`stringRandom`, `stringTruncate`)
+- `number*` for number utilities (`numberClamp`, `numberInRange`)
+- `boolean*`, `date*`, `regexp*`, `error*`, `symbol*`, `bigint*` for other domains
+
+#### 3.2 Common Verb Prefixes
+
+- `is*` - Returns boolean for validation
+- `has*` - Returns boolean for existence checks
+- `get*` / `extract*` - Returns a value
+- `to*` - Conversion operations
+
+### 4. Export Strategy
+
+```typescript
+// Always export public functions
+export const publicFunction = () => {}
+
+// Never export internal helpers
+const internalHelper = () => {}
+```
+
+Keep domain exports in their files and re-export them via the barrel in `index.ts`.
+
+### 5. Common Pitfalls to Avoid
+
+1. Do not rely on `typeof` alone for objects (for example, `typeof null === "object"`).
+2. Do not confuse `NaN` with numbers that cannot be parsed.
+3. Do not treat boxed objects (`new String("x")`) as primitives without checks.
+4. Do not mutate inputs unless the function name and docs make it explicit.
+5. Do not introduce locale-dependent behavior without documenting it.
+
+### 6. Testing Requirements
+
+- Write one test per function.
+- If multiple cases are needed, include them within the same test.