# @basenative/persist 中文文档

规范地址：https://npmcn.com/package/%40basenative/persist/

版本：3\.0\.0
npm 元数据更新时间：2026-10-31T13:48:11.340Z
中文译文更新时间：2026-10-31T15:58:17.747Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40basenative/persist
原文对照：https://npmcn.com/package/%40basenative/persist/?lang=original
项目主页：https://github.com/DuganLabs/BaseNative/tree/main/packages/persist#readme
源码仓库：https://github.com/DuganLabs/BaseNative

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

- 包体积（解压后）：25.7 kB，9 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@basenative/runtime 3\.0\.0
- 首次发布：2026-10-18T05:29:35.003Z
- 最新版本发布：2026-10-31T13:48:10.976Z
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

带有TTL、冲突解决和用于BaseNative应用程序的服务器补充钩子的信号驱动的本地持久性

## 安装

```sh
npm install @basenative/persist
```

也可以使用：`pnpm add @basenative/persist`、`yarn add @basenative/persist`、`bun add @basenative/persist`

## README

# @basenative /持续

带有TTL的信号驱动的本地持久性、冲突解决和一个 server-rehydrate钩。实际上是为BaseNative应用构建的 需要:

-   **恢复飞行中的会话** 跨重载、标签和设备。
-   **保存表格草稿** 没有定制 `useEffect` 管道。
-   **记得上次的选择吗？** （有源滤波器，排序顺序，主题）与TTL 所以它不会永远卡住。

三层，每一层都可以独立组合。

## 安装

```sh
pnpm add @basenative/persist
# Optional — get reactive bindings via signals
pnpm add @basenative/runtime
```

## 第1层-带TTL的扁平KV

```js
import { loadPersisted, savePersisted, clearPersisted } from '@basenative/persist';

await savePersisted('theme', 'dark');                  // forever
await savePersisted('cart',  cart, 60 * 60 * 24);      // 24h TTL
await loadPersisted('cart');                           // null if expired
await clearPersisted('cart');
```

磁盘上信封是 `{ v, t, e }` - value, savedAt-ms， expiresAt-ms-or-null。过期的条目在读时被清除。

遗产 `{...state, savedAt}` 读取形状（t4bs约定） 透明的默认12小时到期-不需要迁移。

## 第2层-信号绑定

```js
import { signal } from '@basenative/runtime';
import { persisted } from '@basenative/persist';

const draft = signal('');
const dispose = persisted('compose:draft', draft, {
  ttlSeconds: 7 * 24 * 3600,
  debounceMs: 300,
});
```

信号从mount上的存储中被水化，然后写入到每一个 改变。通过 `resolve(local, current)` 合并而不是覆盖。

适用于任何信号形状的对象 `@basenative/runtime`，生礁石，或 您自己的原始-任何暴露某些组合的东西 `.value`， `.get/.set`, `.subscribe`.

## 第3层-服务器补水

来自t4bs的“会话恢复”模式 `App.jsx`：

```js
import { hydrateFromServer } from '@basenative/persist';

await hydrateFromServer({
  key: 't4bs:session',
  ttlSeconds: 12 * 3600,
  fetch: () => api.getSession(),
  reconcile: (local, server) => server ?? local, // server is authoritative
  onResolve: (state, { source }) => {
    if (state) setSession(state);
    if (source === 'server') setLoading(false);
  },
  onError: (e) => console.warn('session refresh failed:', e),
});
```

操作顺序：

1.  本地缓存命中→立即发出(`source: 'local'`)所以UI 无需等待网络即可绘制。
2.  `fetch()` 运行→再发出权威结果 （`source: 'server'`）。
3.  保持权威状态。

如果获取错误，local保持不变。

## 存储适配器

```js
import { setStorageAdapter, indexedDbAdapter } from '@basenative/persist';

setStorageAdapter(indexedDbAdapter()); // for big payloads
```

-   `localStorageAdapter()` ——默认;~ 5 mb的帽子。
-   `indexedDbAdapter({ dbName, store })` -选择更大的斑点。
-   `memoryAdapter()` - SSR /测试/工人。

## 示例

### 游戏环节恢复

```js
const session = signal(null);
persisted('t4bs:session', session, { ttlSeconds: 12 * 3600 });
```

### 表单草案

```js
const draft = signal({ title: '', body: '' });
persisted('compose:draft', draft, { debounceMs: 500, ttlSeconds: 7 * 24 * 3600 });
```

### 最后的选择

```js
const filter = signal('all');
persisted('inbox:filter', filter); // no expiry
```

## 链接

-   碱性单氧- [https://github.com/DuganLabs/basenative](https://github.com/DuganLabs/basenative)
-   问题- - - - - - [https://github.com/DuganLabs/basenative/issues](https://github.com/DuganLabs/basenative/issues)
-   文档- [https://github.com/DuganLabs/basenative#readme](https://github.com/DuganLabs/basenative#readme)

## 许可证

apache - 2.0。

## 常见问题

### @basenative/persist 是什么？

带有TTL、冲突解决和用于BaseNative应用程序的服务器补充钩子的信号驱动的本地持久性

### 如何安装 @basenative/persist？

在项目目录运行 npm install @basenative/persist，或使用 pnpm add / yarn add / bun add。

### @basenative/persist 支持 TypeScript 吗？

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

### @basenative/persist 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @basenative/persist 可以商用吗？

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

### @basenative/persist 还在维护吗？

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