# @flare-engine/storage 中文文档

规范地址：https://npmcn.com/package/%40flare-engine/storage/

版本：0\.4\.12
npm 元数据更新时间：2026-11-12T19:48:51.812Z
中文译文更新时间：2026-11-14T21:44:18.838Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40flare-engine/storage
原文对照：https://npmcn.com/package/%40flare-engine/storage/?lang=original
项目主页：https://github.com/grzott/flare-engine#readme
源码仓库：https://github.com/grzott/flare-engine

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：172 kB，12 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- 首次发布：2026-06-09T16:19:46.599Z
- 最新版本发布：2026-11-12T19:48:51.470Z
- 近 30 天下载量：2379（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 17 个）

## 中文简介

长期密钥/值存储,并使用已输入的系统、迁移、保存插槽和JSON进出口

## 安装

```sh
npm install @flare-engine/storage
```

也可以使用：`pnpm add @flare-engine/storage`、`yarn add @flare-engine/storage`、`bun add @flare-engine/storage`

## README

# @flare-engine/储存

为保存游戏和应用程序设置而打入,版本的密钥/值持续. 适配器:原生地上MMKV(sync, sub-milisecond),网络上索引DB,测试用内模. Tiny Zod-ish 计划验证器(`s.string()`, (中文(简体) ), `s.object()`,与(.) `Infer<S>` 类型提取。 仅转发 `Migration[]` 链被验证 `defineMigrationChain` ——差距投出于起步,而非出产. 单文件版本商店( E)`createDocumentStore`)用于设置样式的文档。 冷却出场消毒器`san.*`用于迁移真实持续数据.

## 安装

```sh
bun add @flare-engine/storage
```

## 使用量

```ts
import { createStorage, createMemoryAdapter, s, defineMigrationChain } from '@flare-engine/storage';

const SaveSchema = s.object({
  version: s.literal(2),
  zone: s.number(),
  inventory: s.array(s.string()),
});

const migrations = defineMigrationChain([
  {
    from: 1,
    to: 2,
    // Lift a v1 { zone, items } save into the v2 shape, preserving the player's data.
    migrate: (old: unknown) => {
      const v1 = old as { zone?: number; items?: string[] };
      return { version: 2, zone: v1.zone ?? 0, inventory: v1.items ?? [] };
    },
  },
]);

const storage = createStorage({
  adapter: createMemoryAdapter(), // in-memory: tests/SSR; swap for MMKV on native (below)
  schema: SaveSchema,
  version: 2,
  migrations,
});

await storage.saveSlot('slot1', { version: 2, zone: 4, inventory: ['key'] });
const data = await storage.loadSlot('slot1');
```

在本地,在持久的MMKV适配器中互换. `react-native-mmkv` 是一个 **结构** 端点 - 您构造 `MMKV` 并传入;这个包不依赖它(`createMmkvAdapter` 接受导出 `MMKVLike` 子集 :

```ts
import { MMKV } from 'react-native-mmkv';
import { createStorage, createMmkvAdapter } from '@flare-engine/storage';

const storage = createStorage({
  adapter: createMmkvAdapter(new MMKV()),
  schema: SaveSchema,
  version: 2,
  migrations,
});
```

对设置 doc 使用宽放解析器的单文件存储 :

```ts
import { createDocumentStore, createMemoryAdapter, san } from '@flare-engine/storage';

interface Settings { locale: string; volume: number; }

function parseSettings(raw: unknown): Settings {
  return san.object({ locale: san.string('en'), volume: san.clamped(1, 0, 1) })(raw);
}

const store = createDocumentStore<Settings>({
  adapter: createMemoryAdapter(),
  key: 'myapp:settings',
  version: 1,
  parse: parseSettings,
  onFirstRun: (doc) => ({ ...doc, locale: 'en' }),
});

const settings = await store.load();
await store.save({ ...settings, volume: 0.8 });
```

## 槽头

插槽菜单每节需要一行(“第12天 ^ Kaszuby ^ 6 h slayed”)而无需付费 `loadSlot` 在每一个位置上: 运行每个移位和每个插槽的全图解析, 一个腐败的保存扔出并取下菜单。 通过一个小的,JSON-可串行标题作为第三个论点: `saveSlot`· ; `listSlotHeaders()` 返回时 `{ name, version, header }` 仅从信封中抽出每个插槽,没有迁移和计划。 在没有标题的情况下保存的插槽, 或在标题存在之前写入, 列表中包含 `header: null`; 其信封无法读取列表的槽 `version: null` 财务报告和审定财务报表 `header: null`一个糟糕的插槽永远不会让其他人失望.

```ts
import { createStorage, createMemoryAdapter, s, san } from '@flare-engine/storage';

const SaveSchema = s.object({ day: s.number(), zone: s.string(), inventory: s.array(s.string()) });

// Lenient and never throwing: a header written before `playedSeconds` existed lists it as 0.
const parseHeader = san.object({
  day: san.number(0),
  zone: san.string('unknown'),
  playedSeconds: san.number(0),
});

const storage = createStorage({
  adapter: createMemoryAdapter(),
  schema: SaveSchema,
  version: 1,
  parseHeader,
});

await storage.saveSlot(
  'slot1',
  { day: 12, zone: 'Kaszuby', inventory: ['key'] },
  { day: 12, zone: 'Kaszuby', playedSeconds: 21_600 },
);

for (const slot of await storage.listSlotHeaders()) {
  const label = slot.header
    ? `Day ${slot.header.day} · ${slot.header.zone} · ${Math.round(slot.header.playedSeconds / 3600)} h played`
    : 'Unreadable save';
  console.log(slot.name, slot.version ?? '?', label);
}
```

-   **信头没有迁移 .** `listSlotHeaders` 返回已写入的旧页眉,所以修改页眉形状的消费者会读取旧的形状,除非 `parseHeader` 修复它. `parseHeader` 宽大一点 `Sanitizer<H>` 喜欢 `createDocumentStore`是因为 `parse`; 它也键入 `H`,只运行在 `listSlotHeaders` (单位:千美元)`saveSlot` 按给定键存储页眉),以及使页眉显示为 `null`。 。 。 .
-   **费用.** `listSlotHeaders` 仍然读取和JSON-parses每个插槽的全字符串;它只跳过迁移和计划. 储蓄是每集 CPU 和 不扔合同,而不是 I/O.
-   **覆盖删除标题.** `saveSlot(name, data)` 没有页眉,则去掉槽上一个页眉;传递到每个保存上.
-   无头 `saveSlot` 写同样 `{ version, data }` 信封与以前一样 `loadSlot` 忽略了页眉,所以现有的保存不需要迁移.

见 [API 规格](https://github.com/grzott/flare-engine/blob/main/docs/design/api-specs.md#flare-enginestorage--4kb-gzip)。 。 。 .

## 许可证

阿帕奇 - 2.0

## 常见问题

### @flare-engine/storage 是什么？

长期密钥/值存储,并使用已输入的系统、迁移、保存插槽和JSON进出口

### 如何安装 @flare-engine/storage？

在项目目录运行 npm install @flare-engine/storage，或使用 pnpm add / yarn add / bun add。

### @flare-engine/storage 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @flare-engine/storage 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @flare-engine/storage 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @flare-engine/storage 可以商用吗？

@flare-engine/storage 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @flare-engine/storage 的下载量有多少？

根据 npm 官方下载统计，@flare-engine/storage 在 2026/10/15 – 2026/11/13 这 30 天内被下载 2,379 次，日均约 79 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @flare-engine/storage 还在维护吗？

最新版本 0\.4\.12 发布于 2026/11/13（3 天前）；至今共发布 17 个版本，其中过去 12 个月发布了 17 个；首次发布于 2026/06/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。