CML JavaScript/TypeScript SDK

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

特性

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

安装

npm install @contextmark/cml

快速开始

基本使用

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);

编码模式转换

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

Markdown 转换

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']

手动构建

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

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

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

API 文档

核心类型

CmlMode

CML编码模式枚举：

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

CmlElements

基元类型抽象的单序列：<token>, <separator>, <token>, <separator>, ...<token>

CmlFragments

基元类型的分类双序列：

• tokens: 所有的实体内容
• relations: 所有的关系符 (@, ., +, :, 空格)

主要函数

验证相关

• 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数组

编码模式说明

A模式 (Double Base58)

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

C模式 (Double Base64URL)

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

P模式 (Hybrid Plaintext)

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

Q模式 (Hybrid + Global Base64URL)

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

开发

# 安装依赖
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