@planet-matrix/mobius-model 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planet-matrix/mobius-model",
-  "version": "0.3.0",
+  "version": "0.4.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,143 @@
+# 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: 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.).
+
+## 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.