JavaScript SDK API

包名：@yomitone/javascript
当前版本：0.1.0-dev.5 模块格式：ESM

当前包同时提供平台无关入口、浏览器入口和 Node.js 入口。Node.js 可以直接读取本地 SQLite Data Pack；浏览器可以按需查询分片或由用户主动完整安装。完整辞典不打进 npm package。

入口

导入路径	用途
@yomitone/javascript	平台无关 API、小型数据、自定义 Provider 与浏览器分片
@yomitone/javascript/browser	明确的浏览器入口，不引入 Node.js 模块
@yomitone/javascript/cloudflare	Cloudflare 按需 morphology data + 浏览器本地 Analysis v1
@yomitone/javascript/node	Node.js SQLite Provider 与便捷创建函数

createCloudflareYomiTone(options)

import { ShardedDictionaryProvider } from "@yomitone/javascript";
import { createCloudflareYomiTone } from "@yomitone/javascript/cloudflare";

const dictionaryProvider = new ShardedDictionaryProvider({
  baseUrl: "/yomitone-data/",
});
const yomitone = createCloudflareYomiTone({
  dictionaryProvider,
  baseUrl: "https://your-worker.example/v1/morphology/",
});

const analysis = await yomitone.analyzeText("日本語を食べました。");

Worker 只返回版本化的 Bloom prefilter 与已压缩 morphology chunks；SDK 在浏览器完成校验、 解压、Viterbi 和 Analysis v1。首次 bootstrap 本地实测约 685 KiB，之后按输入读取相关 lexicon/matrix rows，并在实例内缓存。辞典 reading/重音仍由传入的 DictionaryProvider 提供，可以是静态分片、已安装 Data Pack 或自定义 D1 Provider。

本地四组真实句子已和 Native 逐字段对照通过；R4D 也已用合成、不可发布的数据完成真实 Worker/D1 协议试点。但 683,134-byte D1 BLOB 的 CPU 为 14–19 ms，超过 Workers Free 的 10 ms 边界，因此约 1 MB bootstrap 不能使用这条免费 Worker/D1 路径。真实完整数据、生产 延迟、长期配额和滥用控制也未验证；公开接口无法绝对禁止枚举完整辞典。

createYomiTone(options)

创建并返回 YomiTone 实例。

await createYomiTone({ provider });
await createYomiTone({ data: smallArtifact });
await createYomiTone({ dataUrl, fetch: customFetch });

完整辞典推荐使用 provider；对象和 dataUrl 更适合小型数据。

createNodeYomiTone(options)

import { createNodeYomiTone } from "@yomitone/javascript/node";

const yomitone = await createNodeYomiTone({
  dataPath: "./yomitone-local.db",
  // 可选；默认由 dataPath 推导同目录的 *.manifest.json。
  manifestPath: "./yomitone-local.manifest.json",
});

try {
  const result = await yomitone.lookupWord("食べました");
} finally {
  await yomitone.close();
}

要求 Node.js 22.13.0 或更高版本。打开前校验 manifest、SQLite SHA-256、data/database schema、最低 Engine 版本和数据库 metadata；数据库以只读模式打开且不允许加载扩展。

也可以分别创建 Provider：

import {
  NodeSqliteDictionaryProvider,
  createYomiTone,
} from "@yomitone/javascript/node";

const provider = await NodeSqliteDictionaryProvider.open({ dataPath });
const yomitone = await createYomiTone({ provider });

YomiTone.close() 可以重复调用；关闭后再次查询会抛出 provider_closed。当前底层 SQLite 调用是同步的，查询 API 仍返回 Promise；高并发或重查询服务应自行放入 Worker Thread 或 独立工作进程。

ShardedDictionaryProvider

const provider = new ShardedDictionaryProvider({
  baseUrl: "/yomitone-data/",
  fetch: customFetch, // 可选
});

Provider 读取 manifest.json，使用稳定哈希定位查询分片，并在当前实例中复用已经读取的 manifest、分片和查询结果。

BrowserDataInstaller

import { BrowserDataInstaller } from "@yomitone/javascript";

const installer = new BrowserDataInstaller({
  baseUrl: "/yomitone-data/",
});

const status = await installer.status();
await installer.install({ onProgress });
const provider = await installer.createInstalledProvider();
await installer.remove();

• status()：返回是否已安装、数据版本、数据占用、浏览器总用量、配额和持久存储状态；
• install()：逐分片下载并校验 SHA-256，全部成功后才切换活动版本；
• createInstalledProvider()：创建只读取已安装数据、不会回退到网络的 Provider；
• remove()：删除当前数据源的已安装数据。

安装应由用户明确操作触发。它只负责辞典数据，宿主的 HTML、JavaScript 和 CSS 是否能够 离线打开不属于这个类的职责。

这个类只在浏览器入口使用。Node.js 不需要 CacheStorage，而是使用独立 SQLite Provider， 避免要求服务端或 Electron 安装浏览器分片。

await yomitone.lookupWord(query)

按表记、读音、基本形或已支持的活用形执行精确查询。

const result = await yomitone.lookupWord("食べました");

matchedBy 可能包含：

• surface：命中表记；
• reading：命中读音；
• lemma：命中基本形；
• inflected：命中活用形。

活用词条可以同时返回：

• pitchAccents：辞书形重音候选；
• surfacePitchAccents：当前表层活用形重音候选；
• surfacePitchAccentStatus：resolved 表示已有可靠候选，unsupported 表示只完成了 活用还原，尚不能确定表层重音；
• morphology：基本形、活用类型、活用形和底层组件；
• furigana：结构化 Furigana；
• provenance 和 resolverTrace：来源与推导说明。

DictionaryProvider

interface DictionaryProvider {
  lookup(normalizedQuery: string): Promise<LookupMatch[]>;
  dataInfo(): Promise<LookupDataInfo>;
  close?(): void | Promise<void>;
}

Provider 只负责数据访问。语言学结果来自数据构建和引擎规则，不由界面组件临时推导。

错误

code	含义
empty_query	去除首尾空白后没有查询内容
invalid_data	数据、manifest 或分片结构无效
unsupported_schema	数据 schema 版本不兼容
incompatible_engine	数据要求的最低 Engine 版本高于当前 SDK
data_fetch_failed	无法读取指定数据
provider_failed	Provider 查询失败
browser_storage_unsupported	当前环境没有所需的浏览器存储或校验能力
storage_quota_insufficient	浏览器估算的可用空间不足
checksum_mismatch	下载分片与 manifest 的 SHA-256 不一致
data_not_installed	请求离线 Provider 时尚未安装数据
provider_closed	Provider 或 YomiTone 已关闭，不能继续查询

未命中词条不是 exception，而是 warnings 中的 unknown_word。能够还原、但尚无可靠 表层重音的活用形会返回 unsupported_conjugation_accent。