# @bytecask/core 中文文档

规范地址：https://npmcn.com/package/%40bytecask/core/

版本：2026\.7\.5
npm 元数据更新时间：2026-07-16T18:23:57.974Z
中文译文更新时间：2026-11-08T21:49:58.818Z
软件包许可：AGPL-3\.0-only

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

原始 npm 页面：https://www.npmjs.com/package/%40bytecask/core
原文对照：https://npmcn.com/package/%40bytecask/core/?lang=original
项目主页：https://bytecask.net/
源码仓库：https://github.com/jmagly/bytecask

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

- 包体积（解压后）：154 kB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@bytecask/worker 2026\.7\.5
- 首次发布：2026-07-15T08:05:08.822Z
- 最新版本发布：2026-07-16T18:23:57.631Z
- 近 30 天下载量：12109（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

浏览器-内置内容地址为二进制blob store – BLAKE3地址,分级存储适配器(OPFS通过工人,索引DB,内存),dedup,再算,GC.

## 安装

```sh
npm install @bytecask/core
```

也可以使用：`pnpm add @bytecask/core`、`yarn add @bytecask/core`、`bun add @bytecask/core`

## README

# @ bytecask/ 核心

**浏览器- 本地, 内容地址为 blob 存储 .**

将二进制数据存储在索引DB、OPFS或一个输入的API后面的内存中 BLAKE3处理、分解、生命周期核算和回收工具.

```bash
pnpm add @bytecask/core
```

[![npm](https://img.shields.io/npm/v/@bytecask/core?style=flat-square)](https://www.npmjs.com/package/@bytecask/core) [![downloads](https://img.shields.io/npm/dm/@bytecask/core?style=flat-square)](https://www.npmjs.com/package/@bytecask/core) [![license](https://img.shields.io/badge/license-AGPL--3.0-blue?style=flat-square)](https://npmcn.com/package/%40bytecask/core/LICENSE) [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178c6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)

[**快速启动**](https://npmcn.com/package/%40bytecask/core/#readme-quick-start) • 妇女 [**后端**](https://npmcn.com/package/%40bytecask/core/#readme-storage-backends) • 妇女 [**API 密码**](https://npmcn.com/package/%40bytecask/core/#readme-main-api) • 妇女 [**浏览器支持**](https://npmcn.com/package/%40bytecask/core/#readme-browser-support) • 妇女 [**文档**](https://npmcn.com/package/%40bytecask/core/#readme-documentation)

* * *

## 这是什么

`@bytecask/core` 是框架中立的 Bytecask 存储引擎。 它接受 `Blob`, (中文(简体) ), `Uint8Array`,或流出字节并返回小写 BLAKE3 内容 散货 相同内容存储一次, 而生命周期元数据决定 对象是否为活、可收藏或缺失.

| 它规定 | 它故意离开 给主机 |
| --- | --- |
| 内容处理二进制存储 | 记录和关系数据 |
| 索引DB、OPFS和内存适配器 | 用户授权和同步 |
| 重复、参考、GC、对账 | 签名和出版商身份 |
| 配额和诚信差错 | 不可替代数据的唯一副本 |
| 可移植 `blobs/<hash>` 包装 | 产品专用附件工作流程 |

## 要点

-   **BLAKE3 内容身份 :** 稳定的散列支持分解和可移植 名单.
-   **索引DB-第一个持久性:** 无宽跨浏览器存储 数据库依赖性.
-   **可选 OPFS 流线:** 工人支持的大文件 I/O 只有在 选中 .
-   **明确的生命周期模型:** 使用重新计数或对帐 主机列表 .
-   **失败意识写道:** 部分对象在配额、元数据、, 完整性,或流出故障.
-   **无害环境管理和类型脚本:** 输入没有顶级浏览器- 全球的公开导出 进入,所以在SSY期间导入是安全的.

## 安装

安装索引数据库、内存和自动后端选择的核心软件包:

```bash
pnpm add @bytecask/core
```

仅在使用 OPFS 时添加工人包 :

```bash
pnpm add @bytecask/core @bytecask/worker
```

## 快速启动

```ts
import { createBlobStore } from '@bytecask/core'

const store = await createBlobStore({ backend: 'idb' })
const hash = await store.put(new Blob(['hello, Bytecask']))

console.log(hash) // lowercase BLAKE3 hex

const blob = await store.getBlob(hash)
const bytes = await store.get(hash)

await store.close()
```

自动选择尝试索引DB, 然后是 OPFS, 然后是内存并曝光 结果是 `store.backend`。强制为必须保存的档案提供一个持久的后端 永不降为会话记忆.

## 存储后端

| 后端 | 选择 | 持久性 | 最适合 |
| --- | --- | --- | --- |
| 索引数据库 | 默认持久等级 | 浏览器管理, 可驱逐 | 一般文件和附件 |
| 财务处 | 明确或自动倒置 | 浏览器管理, 可驱逐 | 流和大型二进制对象 |
| 内存 | 明确或最后退缩 | 仅会话 | 测试、预览和瞬间数据 |

```ts
const store = await createBlobStore({
  backend: 'idb',
  idb: { databaseName: 'archive-blobs' },
  metadata: { databaseName: 'archive-metadata' },
  verifyOnRead: true,
})

const persistenceGranted = await store.requestPersistence()
const report = await store.reconcile(liveAttachmentHashes)
```

无法使用时强制后端拒绝 。 它永远不会悄悄改变 要求的耐久性模型.

## 生命周期模型

每个商店选择一个权限 :

1.  **存储管理 :** `put()` 创建引用; 平衡所有权与 `ref()` 财务报告和审定财务报表 `unref()`,然后与 `gc()`。 。 。 .
2.  **主机管理 :** 以犬目为纲目而行之 `reconcile(liveHashes)` 用于修复元数据并识别缺失或 未引用字节 .

不为同一档案维护独立的再计算系统 .

## 主要 API

| 导出 | 目的 |
| --- | --- |
| `createBlobStore(options)` | 选择或强迫存储后端 |
| `put`, (中文(简体) ), `get`, (中文(简体) ), `getBlob`, (中文(简体) ), `has`, (中文(简体) ), `delete` | 通过散列存储和取回字节 |
| `ref`, (中文(简体) ), `unref`, (中文(简体) ), `gc` | 库存管理的生命周期核算 |
| `reconcile(liveHashes)` | 从主机授权列表进行修复状态 |
| `subscribe(listener)` | 观察本地字节存储突变结果 |
| `estimate`, (中文(简体) ), `requestPersistence` | 浏览器存储和持续 |
| `packBlobs`, (中文(简体) ), `unpackBlobs` | 移动便携式 `blobs/<hash>` 条目 |
| `BytecaskError`, (中文(简体) ), `QuotaError`, (中文(简体) ), `IntegrityError` | 处理打入的存储失败 |

```ts
const unsubscribe = store.subscribe((event) => {
  if (event.type === 'put') {
    console.log(event.hash, event.refcount)
  }
})
```

变换饲料是存储级和本地到 `BlobStore` 举个例子 它发出 Bytecask 字节/ 生命周期结果, 而不是主机记录的语义或跨 Tab 同步 留言.

## 浏览器支持

-   IndexedDB行为在Chrimium,Firefox,和Playwright WebKit中测试.
-   OPFS的工人行为在Chrimium和Firefox测试.
-   内存存储在浏览器和JavaScript测试环境中工作.
-   该套件仅以无害环境管理为对象并针对现代浏览器.

Playwright WebKit是一个引擎代理,而不是苹果公司的Safari二进制. 将浏览器存储视为可重建的本地副本, 因为持续请求 减少驱逐风险,但不能消除.

## 相关软件包

| 软件包 | 目的 |
| --- | --- |
| [`@bytecask/worker`](https://www.npmjs.com/package/@bytecask/worker) | OPFS任选工作者和流动I/ 欧 |
| [`@bytecask/react`](https://www.npmjs.com/package/@bytecask/react) | 可选反应提供者和钩 |

## 文档

-   [项目研究](https://github.com/jmagly/bytecask#readme)
-   [东道方合同](https://github.com/jmagly/bytecask/blob/main/docs/host-contract.md)
-   [覆盖和浏览器证据](https://github.com/jmagly/bytecask/blob/main/docs/test-coverage.md)
-   [建筑](https://github.com/jmagly/bytecask/blob/main/.aiwg/architecture/ARCHITECTURE.md)
-   [更改日志](https://github.com/jmagly/bytecask/blob/main/packages/core/CHANGELOG.md)

## 警卫

Bytecask验证内容身份,而非出版商身份. 验证签名 在水分不可信字节之前的容器或硬体。 报告脆弱性 通过项目 [安全政策](https://github.com/jmagly/bytecask/blob/main/SECURITY.md), (中文(简体) ), 这不是一个公开的问题.

## 许可证

AGPL-3.0 -仅限. 见 [自由主义](https://npmcn.com/package/%40bytecask/core/LICENSE)。 。 。 .

## 常见问题

### @bytecask/core 是什么？

浏览器-内置内容地址为二进制blob store – BLAKE3地址,分级存储适配器\(OPFS通过工人,索引DB,内存\),dedup,再算,GC\.

### 如何安装 @bytecask/core？

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

### @bytecask/core 支持 TypeScript 吗？

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

### @bytecask/core 支持 ESM 还是 CommonJS？

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

### @bytecask/core 可以商用吗？

@bytecask/core 使用 AGPL-3\.0-only 许可。最严格的 Copyleft：除分发外，通过网络向用户提供基于它的服务也需要开源对应源码。闭源 SaaS 使用前务必评估。以上为概括，不构成法律意见，请以许可原文为准。

### @bytecask/core 的下载量有多少？

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

### @bytecask/core 还在维护吗？

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