mai-kit

主题

@mai-kit/database ​

@mai-kit/database 提供舞萌 DX 游戏数据与素材访问。

MaimaiDatabase 定义与数据源无关的接口，内置的 LXNS 和 Diving-Fish 适配负责连接具体 API 与 CDN。玩家成绩由 @mai-kit/prober 查询。

用法 ​

ts
// db 为任意 MaimaiDatabase 实现
const { songs } = await db.getSongList({ notes: true });
const jacket = await db.getAsset("jacket", songId);
// 可注入 Draw：new Draw({ database: db })

内置适配 ​

ts
import { LxnsMaimaiDatabase, DivingFishMaimaiDatabase } from "@mai-kit/database";

const lxns = new LxnsMaimaiDatabase();
const df = new DivingFishMaimaiDatabase();

启用缓存 ​

ts
import {
  FileSystemCacheStore,
  LxnsMaimaiDatabase,
  MemoryCacheStore,
} from "@mai-kit/database";

// 内存（Node / Web）
const memoryDb = new LxnsMaimaiDatabase({
  cache: {
    store: new MemoryCacheStore({ maxEntries: 512 }),
    ttlMs: 5 * 60_000,
  },
});

// 磁盘（仅 Node）
const diskDb = new LxnsMaimaiDatabase({
  cache: {
    store: new FileSystemCacheStore({ directory: "/var/cache/mai-kit", maxEntries: 2_000 }),
    ttlMs: 24 * 60 * 60_000,
  },
});

错误 ​

包与职责 · 快速开始

接口与模型 ​

名称描述
Alias曲目别名
BuddyNotes宴会场 BUDDY 谱面物量
ChartTagDXRating 社区谱面标签
ChartTagGroupDXRating 社区谱面标签分组
ChartTagQuery查询某张谱面的标签；字段与 prober Score 可结构化兼容。
CollectionGenre收藏品分类
CollectionListQuery收藏品列表查询参数
Genre流派
MaimaiDatabase游戏静态数据与素材访问接口（与具体数据服务无关）。
Notes谱面物量
Song曲目。
SongCollection曲目关联的收藏品
SongDifficulties一首曲目的全部难度
SongDifficulty谱面难度（标准 / DX）
SongDifficultyUtage宴会场谱面难度
SongList曲目列表查询结果
SongListQuery曲目列表查询参数
Version版本
VersionQuery按版本过滤的查询参数
AssetType素材类型
LocalizedTextDXRating 社区谱面标签的多语言文本

LXNS 适配 ​

名称描述
LxnsDatabaseErrorLXNS 静态数据 / 素材适配专用错误（继承 MaimaiDatabaseError）。
LxnsMaimaiDatabaseMaimaiDatabase 的 LXNS 适配：公开 JSON API + 素材 CDN。
LxnsMaimaiDatabaseOptionsLxnsMaimaiDatabase 构造选项
isLxnsDatabaseError类型守卫：是否为 LxnsDatabaseError。

Diving-Fish 适配 ​

名称描述
DivingFishDatabaseErrorDiving-Fish（水鱼）静态数据 / 素材适配专用错误（继承 MaimaiDatabaseError）。
DivingFishMaimaiDatabaseMaimaiDatabase 的 Diving-Fish（水鱼）适配。
DivingFishChartStat水鱼单张谱面的社区成绩统计。
DivingFishChartStats水鱼 /chart_stats 的结构化结果。
DivingFishDifficultyStats水鱼按难度汇总的全站成绩统计。
DivingFishMaimaiDatabaseOptionsDivingFishMaimaiDatabase 构造选项
DIVING_FISH_DEFAULT_BASE_URLDiving-Fish 曲目 API 默认根地址
DIVING_FISH_DEFAULT_COVER_BASE_URL封面 CDN 默认根（https://www.diving-fish.com/covers/{id}.png）
isDivingFishDatabaseError类型守卫：是否为 DivingFishDatabaseError。

缓存 ​

名称描述
DatabaseCache适配器共用的缓存读写与并发请求合并器。
FileSystemCacheStoreNode.js 专用的磁盘缓存存储（实现 DatabaseCacheStore）。
MemoryCacheStore双端可用的内存 LRU 缓存存储。
DatabaseCacheEntry缓存存储的二进制条目。
DatabaseCacheOptionsdatabase 适配器的通用缓存配置。
DatabaseCacheStoredatabase 通用缓存存储接口，Node / Web 均可自行实现。
FileSystemCacheStoreOptionsFileSystemCacheStore 的配置（Node.js only）。
MemoryCacheStoreOptionsMemoryCacheStore 的容量配置。

错误 ​

名称描述
MaimaiDatabaseError静态数据 / 素材访问的通用错误（HTTP 或业务失败）。
MaimaiDatabaseNotImplementedError当前数据源无法实现 MaimaiDatabase 某一方法时抛出的包级错误。
MaimaiDatabaseErrorInitMaimaiDatabaseError 构造参数
MaimaiDatabaseNotImplementedErrorInitMaimaiDatabaseNotImplementedError 构造参数
isMaimaiDatabaseError类型守卫：是否为 MaimaiDatabaseError（含各适配子类）。
isMaimaiDatabaseNotImplementedError类型守卫：是否为 MaimaiDatabaseNotImplementedError。