CML JavaScript/TypeScript SDK

CML是语义时代的Markdown，它让兼具人类可读和机器可运算特征的关系结构片段，成为可大规模计算、任意传输、分布式存储的语义中间层。

特性

- 🚀 高性能: 基于 TypeScript 实现，支持 ESM 和 CommonJS
- 🔧 类型安全: 完整的 TypeScript 类型定义
- 🌐 跨平台: 支持浏览器和 Node.js 环境
- 📦 Tree-shaking: 纯 ESM 导出，支持按需导入
- 📚 文档完整: JSDoc 注释，自动生成 API 文档

安装

``bash
npm install @contextmark/cml
`

快速开始

$3

`typescript
import { CML2Elements, CML2Fragments, IsCML } from '@contextmark/cml';

// 检查CML编码是否合法
try {
IsCML('aeyJ1c2VyIjoidGVzdCJ9QGRvbWFpbi5jb20=');
console.log('CML编码合法');
} catch (error) {
console.error('CML编码非法:', error.message);
}

// 解析为单基元序列
const elements = CML2Elements('aeyJ1c2VyIjoidGVzdCJ9QGRvbWFpbi5jb20=');
console.log(elements);

// 解析为双基元序列
const fragments = CML2Fragments('aeyJ1c2VyIjoidGVzdCJ9QGRvbWFpbi5jb20=');
console.log(fragments);
`

$3

`typescript
import { CML2A, CML2C, CML2P, CML2Q } from '@contextmark/cml';

const cml = 'aeyJ1c2VyIjoidGVzdCJ9QGRvbWFpbi5jb20=';

// 转换为不同模式
const aMode = CML2A(cml); // Double Base58
const cMode = CML2C(cml); // Double Base64URL
const pMode = CML2P(cml); // Hybrid Plaintext
const qMode = CML2Q(cml); // Hybrid + Global Base64URL
`

$3

`typescript
import { toMarkdown, fromMarkdown } from '@contextmark/cml';

// CML 转 Markdown
const markdown = toMarkdown('aeyJ1c2VyIjoidGVzdCJ9QGRvbWFpbi5jb20=');
console.log(markdown); // user@domain.com

// Markdown 转 CML 数组
const elements = fromMarkdown('user@domain.com');
console.log(elements); // ['user', '@', 'domain', '.', 'com']
`

$3

`typescript
import { New, encodeFragmentsCFromDouble } from '@contextmark/cml';

// 手动构建双基元序列
const fragments = New(['user', '@', 'domain', '.', 'com']);

// 编码为指定模式
const encoded = encodeFragmentsCFromDouble(fragments);
console.log(encoded); // c模式编码
`

API 文档

$3

#### CmlMode
CML编码模式枚举：
- A: Double Base58 - 字符集普适性最好
- C: Double Base64URL - 高性能模式
- Q: Hybrid + Global Base64URL - 最小熵增
- P: Hybrid Plaintext - 单层明文混编

#### CmlElements
基元类型抽象的单序列：, , , , ...

#### CmlFragments
基元类型的分类双序列：
- tokens: 所有的实体内容
- relations: 所有的关系符 (@, ., +, :, 空格)

$3

#### 验证相关
- IsCML(encoded: string): void - 检查CML编码是否合法

#### 模式转换
- CML2A(encoded: string): string - 转换为a模式
- CML2C(encoded: string): string - 转换为c模式
- CML2P(encoded: string): string - 转换为p模式
- CML2Q(encoded: string): string - 转换为q模式

#### 解析转换
- CML2Elements(encoded: string): CmlElements - 解析为单基元序列
- CML2Fragments(encoded: string): CmlFragments - 解析为双基元序列
- New(arr: string[]): CmlFragments - 手动构建双基元序列

#### Markdown支持
- toMarkdown(encoded: string): string - CML转Markdown
- fromMarkdown(md: string): string[] - Markdown转CML数组

编码模式说明

$3

- 字符集普适性最好
- 双层base58编码
- 适用于对字符集安全性要求极高的场景

$3

- 高性能模式
- 双层base64url编码
- 适合大规模、高并发处理场景

$3

- 单层明文混编，最小熵增
- 保持最佳可读性与长度比
- 智能判断是否需要编码

$3

- 双层混编
- 在不可读的前提下提供最小熵增
- 通过智能判断减少不必要的Base64转换

开发

`bash


安装依赖

npm install

开发模式

npm run dev

构建

npm run build

测试

npm test

类型检查

npm run typecheck

代码检查

npm run lint

生成文档

npm run docs
``

许可证

本项目采用MIT宽松授权。本项目是对 Context Mark Language (CML)核心规范的标准实现。

原始语言文档 ：doc-war.com/CML

原始协议仓库链接：https://github.com/ContextMark/CML