@hachej/boring-files

中文文档
0.5.1发布于 2026/11/17MITTypeScriptES Module构建来源已验证近 30 天下载 8.6万

版本资源合同和一个Pi FileSystem(磁盘,虚拟或SQLite)上的工作空间提供商.

中文使用文档
文档目录9 节
  1. 代理写入和更改种子
  2. 大文件( blob指针) 和媒体嗅觉
  3. 节点主机
  4. 可选认证的资源传输
  5. 可选工作基特
  6. 当地出版筹备失败
  7. 从已删除的资源存储中移入
  8. 前端修订版提供者
  9. 持久对象应用程序

@hachej/ 无聊的文件

一个工作空间文件的版本资源:合同,和Pi自己的FileSystem上的工作空间提供商(没有Boring文件系统). 读者、出版商和检索能力是可独立注入的;总资源提供者公布实际支助/赠款/可用性/合格保证。 ResourceClient 携带浏览器意图, 不可信主机资源访问 .

出版要求非空想变化和明确的原子化. 信任的边界计算出犬科摘要并检查批准情况;这些不是客户授权的授权字段。 接收确认有效的创建/替换/删除过渡;部分结果保留运行,输入指数和完整目标/视图. 和解是可选的,在要求和解时明确要求和解;未找到并不证明无效.

不透明资源视图ID是提供者范围,与提供者的实际支持/化身相接. 与 import type。 。 。 .

@hachej/boring-files/workspace 出口 createWorkspaceProvider({ identity, fs, journal }): 工作空间文件的提供方( u)文件的一个位置) (中文(简体) ). 来来来来来来来来 FileSystem (磁盘环境,虚拟工作空间或下面的 SQLite后端),主机的工作空间身份和一个日记(createWorkspaceJournal(connection) 从 @hachej/boring-files/journal,收据,意图和SQLite中每个文件的最后20个版本. 修订为字节的Git blob ids. 在工作区队列内进行有条件的写入检查, 记录其意图, 记录其最后收到; 未完成的意向为 unknown 而永不重复播放。 它的主人关闭连接;提供者借用. 节点当前标记 node:sqlite 实验.

提供者接受全部或全无创建、替换和有条件删除,并通过 renaming.rename它拒绝工作视图和文件夹的变异而未产生任何效果。 逻辑路径与工作空间根相对;其真实位置会离开根的路径被拒绝. 单个文件在原子上被每个后端所取代;多文件批次只被SQLite后端所取取取取取取取取取取取取取取取取取取取取取取取取取取分取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取的取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取 访问控制是主机的,位于工作空间边界:在工作空间内没有每个文件的权限,外部撤销的栅栏没有执行.

代理写入和更改种子

代理写作被观察到,从未收到(所有权裁决 2) (中文(简体) ). provider.record({ path, before?, after, source: 'agent', conversationId? }, access) 是文件守护者@hachej/boring-agent/file-guard呼叫一个Pi write 或者说 edit 成功: 文件的历史通过 source: 'agent' (和已替换的修订本, source: 'observed',当 before 中包含其字节,变化反馈到 agent 活动。 它从来不写出版日记 也不刻薄收据 它不进入提供者的队列(守卫已经在它内部运行),因此从队列中调用它不能陷入僵局. 历史条目( E)saves, (中文(简体) ), catalog.history携带 source数字 : publish, (中文(简体) ), agent, (中文(简体) ), observed (单位:千美元)keep 并取代订正案), rename 或者说 delete (受影响的保留版本)。 历史仍然是每个内容修订一行,而不是一个操作日志;收据保留每个有条件的突变. 重命名保留了两条路径上被移动的版本;删除保留了被删除的版本而不发明墓碑修订. savedAt 仍然是该版本在该路径上首次被记录的节省时间,而不是单独的删除时间戳.

provider.changes({ since?, signal }, access) 是每个文件视图的一个更改种子: a AsyncIterable 联 合 国 { kind: 'change', path, revision | null, source: 'publish' | 'agent' | 'poll' | 'watch', seq, at },命令 seq 并可以从 since (最后一个) seq 见; changeHead() 是"现在"。 提供者保留最后一个 changeBuffer 事件( 默认 1024 ); 光标比此大, 从另一个提供者的寿命或此时间之前, 以及一个落在后面的听众得到 { kind: 'resnapshot', seq, at }: 重新装入显示的一切, 然后继续 。 事件为无效提示;字节和日记保持权威. 资料来源:有条件写作(publish, (中文(简体) ), record (单位:千美元)agent, (中文(简体) ), poll 而有人听从 watchLingerMs 之后,默认为 30 s),文件系统本身 watch (单位:千美元)watch; 已报告的目录为 { revision: null, directory: true }) (中文(简体) ). SQLite文件系统报告通过自己的连接即刻写出,并每隔一秒钟为其他连接投票. 当文件系统无法监视时( 虚拟和远程环境报告) not_supported),主机呼叫 provider.poll() 在每个代理回合的结尾:没有路径,它会将每个文件都拖走(不是) .git 或者说 node_modules;第一次呼叫取了基线,后来的报告更改了,新建并删除了文件. A 类 bash 写作只得到改变事件,从没有历史。 在最后的收听者离开收看者停留后,然后关闭;在没有收看者打开时所做的更改未知,因此第一个收听者随后使收看者附件成为 resnapshot (保持连接的客户端从未受到影响). changeIncarnation 命名提供者寿命: 与另一个光标一起发送的光标 incarnation 是一个 resnapshot 不管号码多少. provider.close() 结束每条变化流,关闭监视器并放下收听器.

接收范围按工作空间身份、主、范围和发起人划分。 同样承诺的重试返回原始收据;更改参数冲突。 被拒绝的操作不保留身份证。 工作空间早期化身的收据为 unknown。未找到的搜索不能重放不确定的操作.

@hachej/boring-files/publication 是浏览器安全。 它能捕捉请求字节,用WebCrypto来计算出一个版本的Canonic SHA-256文摘,并剖析出结果形状. 文摘载有 boring-publication-v1:sha256: 并将格式标识符装入散列有效载荷。 消费者还必须根据自己的请求检查经营、目标、范围和指数关联。 该模块没有授权。 SQLite 连接( S)openNodeConnection 从 @hachej/boring-files/sqlite)是一个单独的服务器入口.

@hachej/boring-files/sqlite 出口 openNodeConnection(filename, settings?) 联合国 node:sqlite 作为文件 SqliteConnection和 openNodeDatabase(filename, settings?) (已配置) DatabaseSync,对于皮的公共适配器: SqliteStorage.open(new NodeSqliteDatabase(openNodeDatabase(file, settings)))) (中文(简体) ). settings 实值 SqliteSettings { journalMode?: 'wal' | 'delete' | 'truncate' | 'persist', lockingMode?: 'normal' | 'exclusive', busyTimeoutMs?, synchronous?: 'off' | 'normal' | 'full' | 'extra', tempStore?: 'default' | 'file' | 'memory' }; 缺失的字段来自 sqliteSettings.localDisk (WAL,正常锁定,5s繁忙超时,完全同步:设置存在前的行为). sqliteSettings.networkFilesystem 用于一个进程,在 NFS 上拥有文件,例如 EFS: 回滚日记, exclusive 锁定打开时的锁, 10 s 繁忙的超时, 完全同步, 临时的内存表格; 与文件的另一个连接失败 SqliteLockedError (单位:千美元)code: 'sqlite-locked')在繁忙的超时后. 名称和价值允许列入清单(TypeError 否则,在文件打开之前; 没有自由形式 pragma 。 设置在 @hachej/boring-files/sqlite-settings (纯度,浏览器安全; sqlitePragmas(settings) 浏览器的 SQLite Wasm 使用,并且 npm run check 拒绝 PRAGMA journal_mode编号 :locking_mode 其他任何地方的任务。 日记,计量分类账和SQLite文件系统借出一个连接,从不设置平板电脑.

@hachej/boring-files/sqlite-filesystem 出口 openSqliteFileSystem({ connection, workspace, cwd }): 一个 Pi FileSystem 其正则文件和目录为工作空间的行 SqliteConnection (单位:千美元)openNodeConnection, (中文(简体) ), durableObjectSqliteConnection,或 openBrowserSqliteConnection 从私人,未公布 @hachej/boring-browser/sqlite,仅可在此单列坡内使用) incarnation 这些行。 像皮的一样 NodeExecutionEnv (这是皮的) write 工具依赖, writeFile 创建缺少的父目录; 属于文件的父目录仍然失败 。 给 createWorkspaceProvider 是 SQLite 工作空间后端(文件的一个位置:多文件有条件批次在一个交易中执行,当日记使用同一连接时连同收件一起执行. 它执行Pi 1.2的满分 FileSystem (读者: scanLines 是阿皮自己来的 LineScanner,网页目录阅读器,以及民调 watch和回答与皮自己的 FileErrors, 因此此条目载重 @earendil-works/pi-durable/env (Pi的便携式合同,没有发动机):安装 @earendil-works/pi-durable 带着它 此套件的其他条目不需要 Pi.

见 脚手架指南 财务报告和审定财务报表 资源设计。 。 。 .

大文件( blob指针) 和媒体嗅觉

大型或二进制文件(可达100 MB)可以活在主机的blob商店中,作为不可变的blob,而工作空间则在其位置上持有一个小指针文件, <name>.blob.json 有介质类型 application/vnd.boring.blob+json数字 : { "boring:blob": 1, "id", "sha256", "size", "type", "name" }。在位字节是提供商的业务;指针是提供商代表一个巨大的不可移动的blob,像任何文件一样通过工作空间的一个提供商写作并阅读(没有第二名,没有同步). 主机服务字节 GET <blobBase><encodeURIComponent(id)> (默认) /_files/(b) 同一来源,检查每项请求的进入和设定处置, nosniff 和一个CSP. @hachej/boring-files/blob (纯,浏览器安全)导出:

  • parseBlobPointer(bytes | text): 严格(输入 BLOB_POINTER_MAX_BYTES =4 KB,UTF-8 JSON,每个字段都有其类型,64个小写十六进制数字,一个非负式安全整数大小,一个介质类型,一个没有路径分隔符的名称. 它返回指针, { kind: 'unsupported-version', version } 高级 boring:blob (将文件显示为JSON并说出"更新格式"),或 undefined。主机以相同的功能验证.
  • checkBlobBase(base): 从一个开始的同源路径 /一个计谋,一个宿主, //,反斜或白色空间是一个 TypeError。 。 。 . blobItemOf(pointer, base) 财务报告和审定财务报表 resolveBlobPointer(bytes, base) 给 { name, size, type, url }观众唯一看到的.
  • withBlobPointers(provider, base): 作为列表的修订提供者读取: a 的每个指针文件 list 或者说 search 页面载 blob (单位:千美元)FileEntry.blob),通过同一个提供者读取一次. 读取仍然返回指针的字节.
  • BLOB_POINTER_MEDIA_TYPE, (中文(简体) ), BLOB_POINTER_SUFFIX, (中文(简体) ), BLOB_POINTER_VERSION, (中文(简体) ), DEFAULT_BLOB_BASE, (中文(简体) ), isBlobPointerPath 编辑 BlobPointer 编号 : BlobItem 类型.

@hachej/boring-files/file-types 是一个文件的表格. sniffMediaType(head) (通过最多 SNIFF_BYTES = 8 KB)名称 PDF, PNG, JPEG, GIF, WebP, HEIC/HEIF (ISO-BMFF) ftyp 品牌: heic, (中文(简体) ), heix, (中文(简体) ), hevc...是HEIC吗; mif1编号 :msf1 hEIC是一个HEVC相容的品牌,HEIF其他的,没有使用AVIF品牌的称号),并且单从头拉链文件: OpenDocument and EPUB 由所存储 mimetype 条目, docx/xlsx/pptx 乘以 a [Content_Types].xml 条目,然后是存储时的主要部分类型,否则是后期条目的文件夹(word/, (中文(简体) ), xl/, (中文(简体) ), ppt/) (中文(简体) ). 头从未被夸大([Content_Types].xml 几乎总是被去充气,而充气在浏览器中是同步的,所以其大小在数据描述符中的zip不主张. 否则,无效的 UTF-8 字节为 NUL text/plain,一个从不凌驾于名字之上的弱答. delimitedTextType(path, head) 在字节为文本时, 表示扩展名的 CSV 或 TSV . @hachej/boring-agent/file-types 读取此表并读取头部大小;它只保留自己的路由类型.

节点主机

@hachej/boring-files/node-http 桥 node:http 转到这些软件包的获取处理器 : webRequest(incoming, url, { signal, maxBytes }) 在字节盖下首先读取身体(从未读取) Readable.toWeb (b) 提出现场请求,而取消请求会影响这一进程) sendWebResponse(response, outgoing, { signal }) 一次冲出信头, 保留每个信头 set-cookie,等待着 drain 当套接字满后,当客户端断开时取消网络正文。 服务器使用的范例; npm run check 拒绝手写回复副本 examples/。 。 。 .

可选认证的资源传输

@hachej/boring-files/remote 出口 createResourceClient 财务报告和审定财务报表 createResourceHandler。两者都是对现有资源合同的适配器。 他们不导入 Pi 运行时间、 文件系统或数据库 。 客户端执行 ResourceClient· ; publication: true 选择 publish, (中文(简体) ), rename 财务报告和审定财务报表 delete,以及 reconciliation: true 选择 lookup。处理器借用读者、可选的出版者、重命名者、删除者和查找者。 它从来没有关闭他们.

const handler = createResourceHandler({
  authenticate: request => host.authenticateResourceRequest(request),
  reader: provider,
  publisher: provider.publication,
  lookup: provider.reconciliation,
  renamer: provider.renaming,
  deleter: provider.deletion,
});
const client = createResourceClient({
  identity: { principalId, scopeId, initiatorId },
  endpoint: 'https://example.invalid/resources',
  fetch: authenticatedFetch,
  publication: true,
  reconciliation: true,
});

publication: true 需求 reconciliation: true (类型和构造器):其识别被丢失的变体 unknown,只有检查才能解决. 一个只读的客户端也没有设置 。 处理器为未安装的能力回答 405;客户端选择内置不授予服务器权限.

信任的认证返回 ResourceAccess 或无效。 其可选信号代表主机撤销;处理器将其与请求取消合并. 客户身份是预期的反应元数据,绝不是权威. 主办方拥有证书,来源/CSRF/CORS政策,端口路由和提供者封口. 注入的抓取必须尊重 redirect: 'error',保留取消并永远不要重试效果。 绑定一个处理器到主机所选择的提供者能力. 浏览器 JSON 无法授权访问或提供可信赖的文摘或批准 .

私人版本的JSON信封在任何同步工作之前会捕捉出出版字节. 协议版本2载有字节作为cononical base64文本(版本1整数组被拒绝). 默认限制为每个序列化请求4个米B和每个序列化响应8个米B,可配置最多64个米B. 进入的身体使用有限度的生长缓冲. 这些是被接受的信息限制,而不是对获取分配,提供者输出,本地请求捕获,JSON扩展或文摘内存的限制. 主机必须将其信任的投入和提供者的生产分开.

全收或全收必须匹配被捕获的操作,犬科文摘,演员和完整的目标过渡. 收货单是保留下来的,但并不确定联系。 更改请求在发出前被拒绝;部分确认不合格,成为未知数。 在添加运输担保之前,真正的部分提供者必须订立其接收合同.

运输出错、不匹配或超规模的确认和中止观察产生未知的出版/查询结果。 他们从来没有制造一个已知的不承诺否认 或提供者没有找到, 并且从来没有触发回放。 读取失败无法使用 。 查询检查操作和演员协会;呼叫者仍然对照其捕获的原始尝试检查摘要和过渡. 单凭行动ID无法证实这些论点。 未找到不能授权重播 .

撤销会抑制披露直到处理器构建其响应;已经交付的字节无法被撤回. 中止观测不能证明提供者终止、回滚或原子撤销围栏。 提供者的例外和响应序列化失败可能跟随承诺,因此客户端保留了不确定性. 工作空间提供者申报的担保保持不变.

运行 node fixtures/resource-transport.mjs 用于通过真实的要求/响应对象进行虚构的精确保存和检索。 公共产出测试还组成了本土工具任务和丢失的识别标记调节. 被孤立的文档消费者用严格的类型和没有安装Pi,代理或React的浏览器捆绑来练习这个适配器. 这些检查不合格已部署的HTTP,浏览器身份政策或远程提供者生命周期.

@hachej/boring-files/text 供给共享纯度 applyTextEdits 转换和输入解析器。 编辑按顺序运行,需要独特的非空的精确匹配并保存未触动的白空间. 编辑失败拒绝整个转换 。 它没有执行I/O,也没有批准.

可选工作基特

@hachej/boring-files/git 需要钉入 [email protected]。 。 。 . createGitRepository 借给公众 PromiseFsClient,绝对规范目录、主机作者和当前 authorize(operation) 调用。 回调让绑定的呼叫者访问整个所选寄存器,包括工作树和元数据. 唯一准确 true 获得赠款。 它在队列获取后运行,并在返回结果前再次运行. 在呼叫者之间共享一个存储器实例 。 它的队列只将这些调用序列化;其他实例,原始文件系统作者和化名需要基础主机政策. 相对的参数验证并不限制不受限制的文件系统或同义链接目标.

createEnvGitFs(fileSystem, context) 这是 PromiseFsClient 超过一分 FileSystem (单位:千美元) ExecutionEnv'文件':每个Git读取和写出都经过这个环境,所以它的封口也适用于Git. 文件作为模式读取 0o100644 (Pi的文件合同没有模式) 符号链接被拒绝(ENOSYS从来没有跟随.

方法是: init矩阵 status, (中文(简体) ), add,仅限索引 remove, (中文(简体) ), commit,二十进 log, (中文(简体) ), branches, (中文(简体) ), branch, (中文(简体) ), checkout 财务报告和审定财务报表 diff. Diff比较精确的树指针/对象ID,索引和工作树. 它返回已更改的blob路径、模式、对象ID和字节数组,包括未跟踪的工作树文件。 它排除 .git,拒绝不支持的条目类型,并报告限制错误而不短短成功。 默认返回内容限制为100个文件和1个MIB. Traversal是串行,但上游可以在检查字节限制前分配一个完整的blob. 这些限制不约束峰值内存或寄存器的倒转成本. 状态和工作树 diff 禁用本地索引刷新 .

主机拥有文件系统的封存,证书和处理. 没有安装网络传输. 取消在本地操作周围和diff traversal进行检查;它不能回滚Git突变. GitOperationError.effects 区分执行前拒绝与可能的先前突变. Git业务没有耐用业务收据,没有有条件的公布或失事修复保证.

当地出版筹备失败

PublicationNotDispatchedError 从 @hachej/boring-files/publication 识别远程客户端无法发送的有效出版请求。 内容 operationId 识别引用。 本地字节限制,不支持的原子,文摘,请求-构建和发送前取消失败都使用这个错误. 错误不能确定先前尝试使用同一操作ID的结果. 保留和调和任何先前的不确定企图.

一旦调取回调, 运输例外、 HTTP 错误和无效的确认仍然保留 unknown,包括一个在实施后投出相同错误等级的回调. 检查 not-found 仍然不能证明中断的请求没有效果。 文本控制器只使用被打出的错误来进行新生成的操作,释放出此尝试,这样用户就可以保存被更正的草稿.

SQLite 读取并接收对 SQLite 工作空间后端使用延迟读取交易的浏览; 有条件的写入保留它 BEGIN IMMEDIATE 其文件和收据的交易。 测试持有独立的WAL写作交易,并通过提供者读取之前承诺的文件和收件. 这符合 WAL 争论大小写; 打开数据库和任意 SQLite 锁定模式仍然需要写入访问或等待 .

从已删除的资源存储中移入

SQLite 资源存储 @hachej/boring-files/sqlite (单位:千美元)openSqliteResources, (中文(简体) ), SqliteResourceProvider 及其选项类型)是 已删除。 其文件成为工作空间的文件; SqliteConnection 财务报告和审定财务报表 openNodeConnection 留下来 @hachej/boring-files/sqlite。 。 。 . 一个主机,每个瞄准镜保留一个有行的存储器(这里的当前接合固定器)打开一个 SQLite 后置的工作空间 同一数据库中的范围:

旧电话新电话
openSqliteResources({ filename, providerId, authorize })connection = openNodeConnection(filename), (中文(简体) ), journal = createWorkspaceJournal(connection),然后每个范围 fs = openSqliteFileSystem({ connection, workspace: scopeId, cwd: '/workspace' }) 财务报告和审定财务报表 createWorkspaceProvider({ identity: { providerId, instanceId: scopeId, incarnation: fs.incarnation, viewId: 'published' }, fs, journal })
openSqliteResources({ connection, ... }) (永久目标)同样的电话与 durableObjectSqliteConnection(ctx.storage) 从 @hachej/boring-files/sqlite-durable-object
authorize(action, target, access) 在商店里主机在调用工作空间提供者之前检查其政策; shared/sqlite-workspaces.mjs 显示一种方式( 已执行操作的被拒绝的写入和拒绝的查找读取) unknown(中文(简体) )
provider.close()connection.close() 由连接的拥有者
(单位:千美元) delete 变动附有所观察到的修订的有条件出版物,或 provider.deletion.delete({ path: locator, expectedRevision, operationId }, access)
修改为随机编号; 保存相同的字节做了新的修改修改为 Git blob ids: 相同的字节保留其修改,以及 before 等于 after 是有效的承诺更改
每次订正保留每个文件的最后20个版本(createWorkspaceJournal(connection, { historyLimit }); 较老的读取 unavailable

现有存储数据库没有迁移: boring_documents 行不由工作空间后端读取 。 复制每个当前 将创建或从文件开始输入工作空间.

前端修订版提供者

@hachej/boring-files/revision-handler 为现有的工作空间提供商提供服务。 这个 主机解决其 OAuth 会话,并根据每项请求选择工作空间:

const handleFiles = createRevisionHandler({
  resolve: async request => {
    const session = await authenticate(request);
    if (!session) return null;
    return {
      provider: workspaces.workspace(session.workspaceId),
      access: {
        principalId: session.userId,
        scopeId: session.workspaceId,
        initiatorId: session.userId,
      },
    };
  },
});

authenticate 财务报告和审定财务报表 workspaces 是主机对象。 导入 createRevisionHandler 从 @hachej/boring-files/revision-handler。如果收购返回租赁, 包含 release管理者保留它,直到基本作业结束, 包括在请求取消之后.

在浏览器中导入 connectRevisionProvider 从 @hachej/boring-files/revision 并按选定工作区连接一次:

const revisionProvider = await connectRevisionProvider({
  endpoint: new URL('/api/workspace', location.origin),
  fetch: request => fetch(request),
});

同一路线也回答 createResourceClient 联 合 国 @hachej/boring-files/remote数字 : 资源呼吁(read, (中文(简体) ), publish, (中文(简体) ), lookup, (中文(简体) ), rename, (中文(简体) ), delete(没有 装订信头由 createResourceHandler 与解析访问,所以 信封的身份必须与之相匹配,有条件的写法拒绝 stale 修订版 与 conflict检查发送的装订信头(409 用于另一个 工作空间);列表和更改种子总是需要它. 一个只服务于 createResourceHandler (例如,2004年,纽约) /api/resource继续用同样的 客户端; connectRevisionProvider 发现失败(405),这意味着没有列名.

绑定从认证中发现身份和工作空间化身 服务器。 当选定工作空间发生变化时重新连接 。 它会暴露 list, (中文(简体) ), 文件名 search,保留 history, (中文(简体) ), locate, (中文(简体) ), read, (中文(简体) ), publish, (中文(简体) ), lookup, (中文(简体) ), rename, (中文(简体) ), delete 财务报告和审定财务报表 changes({ since?, signal }),工作空间的改变反馈.

const moved = await revisionProvider.rename?.({
  from: revisionProvider.locate('draft.md'),
  to: revisionProvider.locate('final.md'),
  expectedRevision: loaded.snapshot.ref.revision,
  operationId: 'move-draft-1',
});
const removed = await revisionProvider.delete?.({
  path: revisionProvider.locate('final.md'),
  expectedRevision: loaded.snapshot.ref.revision,
  operationId: 'remove-final-1',
});

这些方法发送 rename 财务报告和审定财务报表 delete 在同一认证文件上的类型 终点. from, (中文(简体) ), to 财务报告和审定财务报表 path 为: ResourceLocator而不是绳子 两者都要求 当前源修改; 重命名时也需要在同一处缺少目标 提供者/视图和现有的父目录。 使用直接工作空间呼叫器 provider.renaming.rename(request, access) 财务报告和审定财务报表 provider.deletion.delete(request, access)。 。 。 . 重命名收件是内容相同的删除/ 创建对; 其种子 释放出旧路径 revision: null 然后是新途径的修订,两者 source: 'publish'。 。 。 . 删除发射 revision: null. Stale 修订和现有文件目标冲突. 相同的操作ID重试和 lookup 返回原始收据;已更改 参数冲突。 丢失的回复保留 unknown从不自动重试. createRevisionHandler 从选定的提供者安装这些能力 并持有同样的工作空间租约,直到他们解决。 一般资源处理器 安装 renamer编号 :deleter 当然 文件夹、 递归删除和文件树 重命名/删除控件不属于此端点递增的一部分.

两个操作都使用工作空间队列和 Pi 的本地 renameFile编号 :remove。 。 。 . SQLite(包括持久对象适配器)再利用这些文件系统变异 当日记分享其连接时,在字节/历史/收件交易中. 磁盘/远程后端保留其现有的崩溃窗口:没有效果 已完成的日记收据为 unknown. 贝壳作家仍然在排队之外.

饲料是 GET <endpoint>?op=changes[&since=<seq>&incarnation=<id>] 与绑定头相接: 服务器发送事件( e)event: ready 然后是现世的后世和供养者 event: change 或者说 event: resnapshot 与 id: 下至JSON事件 data:页:1 注释行数 heartbeatMs (单位:千美元)createRevisionHandler({ resolve, heartbeatMs }), (中文(简体) ), 默认 15 s). 这是一个没有队列的平流响应( 以推为主), 所以是一个缓慢的客户端 花费提供者的限定回放缓冲器和 a resnapshot内存 处理器; 撤销会丢弃任何未读的 。 它运行在节点和工人上 一样。 操作者持有工作空间租赁 溪流的生命和 当客户端断开或访问信号中断时释放它; 请求 主机拒绝,或者其约束性名称是另一个工作空间或身份,但没有得到 事件(403或409)。 客户端在交付的后几后重新连接,与 备份,直到其 signal 中止;拒绝结束为 RevisionError。 。 。 . 所有写作都使用有条件的发布; 上传新文件需要缺发, 并且替换一个需要精确的资源修订。 未知结果必须 在上传到该路径之前通过操作ID调节.

目录默认隐藏 Git- ignored 文件、 依赖/ 构建文件夹和内部 元数据。 配置 createWorkspaceProvider({ ..., catalog: { defaults: false, filter: entry => ... } }) 来推翻他们 过滤器规范演示文稿, 不 进入控制。 主机授权整个所选的工作空间. 列出 不跟随符号链接。 平地取景是一种活生生的地貌,不是被冻结的快照; 在同一修改后刷新。 在配置中拖曳 maxEntries (违约10万)明显失败. A. 历史 工作空间日记,不是 Git 承诺,也不是导入文件系统的以往历史 .

文件搜索( @ picker, 树的过滤器) 并上传此路径 还有: search 是目录请求, 而上传是有条件的创建 (单位:千美元)expected: absent与任何其他出版物一样,有收据。 没有 要服务的单独搜索或上传路径.

createRevisionHandler({ resolve, maxFileBytes }) 最大文件名称 写入可能带入字节( 默认为 3 MiB; 最多) 大约48米B). 字节作为 Base64 旅行,所以处理器大小为其资源 请求和对该限制的答复(至少4个小米B和8个小米B)。 一个更大的文件 获得键 file_too_large 结果({ path, size, limit, reason }和 无所写; 重放日志保存过的操作 记录结果。 大于运输载体的请求得到答复 413, 客户报告为 unavailable (明确拒绝)。 约束 (单位:千美元)GET 无 op将限制命名为 limits.maxFileBytes· ; connectRevisionProvider 将其请求大小显示为 maxFileBytes,且文件树在发送前拒绝更大的上传. 提供者自己的文件系统可能拒绝一个较小的文件(SQLite:1 900 000) 默认字节). 此 API 不提供流上传 .

持久对象应用程序

一个 Cloudflare 持久对象将它的工作空间保存在自己的SQLite存储器中,而库与节点主机一样与之相接. 每个 块是节点示例使用的一个,与 durableObjectSqliteConnection(ctx.storage) 从 @hachej/boring-files/sqlite-durable-object 替换 openNodeConnection。工作空间及其日记共享一个连接, 所以一个多文件保存, 并且它的收件被输入到其中 transactionSync数字 :

import { durableObjectSqliteConnection } from '@hachej/boring-files/sqlite-durable-object';
import { openSqliteFileSystem } from '@hachej/boring-files/sqlite-filesystem';
import { createWorkspaceJournal } from '@hachej/boring-files/journal';
import { createWorkspaceProvider } from '@hachej/boring-files/workspace';
import { createRevisionHandler } from '@hachej/boring-files/revision-handler';

// In the object's constructor: one connection and journal, one provider per workspace the object serves.
const connection = durableObjectSqliteConnection(this.ctx.storage);
const journal = createWorkspaceJournal(connection);
const fs = openSqliteFileSystem({ connection, workspace: workspaceId, cwd: '/workspace' });
const provider = createWorkspaceProvider({
  identity: { providerId: 'files', instanceId: workspaceId, incarnation: fs.incarnation, viewId: 'published' },
  fs,
  journal,
});

// The object's HTTP route: the host authenticates the request and picks the workspace it selected.
const handleFiles = createRevisionHandler({
  resolve: async request => {
    const session = await authenticate(request);
    if (!session) return null;
    return { provider: this.providerFor(session.workspaceId), access: { principalId: session.userId, scopeId: session.workspaceId, initiatorId: session.userId } };
  },
});

history 是日志对每个文件的保留修改, 首先是最新的, 与 savedAt 以毫秒计; 此选项之前已保存 日记记录时间报告 savedAt: 0。浏览器的连接方式如下: connectRevisionProvider({ endpoint, fetch }) 从 @hachej/boring-files/revision。每个范围都是自己的工作空间(按键为: workspace),因此,只从 提供者 resolve 返回.

版本与发布记录

@hachej/boring-files 共发布 98 个版本,首次发布于 2026/10/12;过去 12 个月发布了 98 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.5.1latest2026/11/17今天
0.5.0next2026/11/133 天前
0.4.852026/11/125 天前
0.4.842026/11/125 天前
0.4.832026/11/125 天前
0.4.822026/11/116 天前

关于 @hachej/boring-files 的常见问题

@hachej/boring-files 是什么?

版本资源合同和一个Pi FileSystem(磁盘,虚拟或SQLite)上的工作空间提供商.

如何安装 @hachej/boring-files?

在项目目录运行 npm install @hachej/boring-files,或使用 pnpm add / yarn add / bun add。

@hachej/boring-files 支持 TypeScript 吗?

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

@hachej/boring-files 支持 ESM 还是 CommonJS?

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

@hachej/boring-files 需要什么版本的 Node.js?

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

@hachej/boring-files 可以商用吗?

@hachej/boring-files 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@hachej/boring-files 的下载量有多少?

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

@hachej/boring-files 还在维护吗?

最新版本 0.5.1 发布于 2026/11/17(今天);至今共发布 98 个版本,其中过去 12 个月发布了 98 个;首次发布于 2026/10/12。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。