@happyvertical/smrt-web

中文文档
0.62.1发布于 2026/11/17TypeScriptES Module近 30 天下载 2万

SMRT 浏览器客户端数据运行时间: 键入收集厂将客户端-数据引擎包入生成的 REST 客户端

中文使用文档
文档目录16 节
  1. 安装
  2. 快开始
  3. 数据行为
  4. 可选能力
  5. 持久离线写入
  6. 通过您自己的服务器操作进行离线写入
  7. 清理共享设备的陈旧数据
  8. 已读缓存
  9. 实时无效
  10. 更新认识
  11. 引擎边界
  12. 公共API团体
  13. WebMCP能力曝光
  14. 宣布取消执行
  15. 每个文档都锁定工具名称
  16. 发展

@happy垂直/smrt-web

生成的 s-m-r-t REST 集合的框架不可知浏览器数据运行时间 。 这个 将显式生成的收集定义变成缓存的、被动的、, 乐观的客户端收藏,同时将基础数据引擎放在后面 s -m -r.

用于浏览器侧收藏状态, 共享请求分解, 离线 写入、 坚持读取缓存和活化无效 。 丝绒绑住 @happyvertical/smrt-svelte/web。 。 。 .

查询后表面可以使用 createSmrtWebQuery(collection, transport) 改为 获取一个划线的页面 。 可见运行更新状态; background, (中文(简体) ), prefetch,以及 silent 运行远离可见状态。 控制器保留 刷新时 stale 行可用, 取消替换可见行, 并且可以 附加一个查询范围实况订阅.

数据表面行动使用情况 executeSmrtWebDataSurfaceAction(transport, request)。 。 。 . 其请求载有服务器发布的修订版,并附有适用性 键; 浏览器规范化器拒绝格式错误、大小过大或不匹配 在到达UI状态前预览/应用结果. 认证的服务器仍然 获得权威并验证确认符.

安装

pnpm add @happyvertical/smrt-web

快开始

s-m-r-t的 Vite 插件通过 @happyvertical/smrt-virt-web 虚拟模块 :

import {
  createSmrtCollection,
  createSmrtWebClient,
} from '@happyvertical/smrt-web';
import { getCollectionDefinition } from '@happyvertical/smrt-virt-web';

const client = createSmrtWebClient();
const products = createSmrtCollection(
  getCollectionDefinition('products'),
  { basePath: '/api/v1', client },
);

await products.preload();
console.log(products.toArray);

const transaction = products.insert({
  id: crypto.randomUUID(),
  name: 'New product',
});
await transaction.isPersisted.promise;

传出同样的 client 用于共享缓存身份的相关收藏, 飞行中请求中断, 和关系产生的无效.

数据行为

  • 读取的读取是陈旧的,同时重新验证; staleTimeMs 默认为30秒.
  • 同时期的同义读取连接到一个网络请求中 .
  • 插入是乐观的,如果持久性失败则会退后.
  • initialData 种子 SSR-水分行,不重复第一手取取取.
  • 公共行为平面 DTO; 数据引擎类型和虚拟字段不交叉 软件包边界.

可选能力

能力是每次收集选入的,并经过稳定的生命周期接合. 没有它们的收藏保留了基本的运行时间行为.

持久离线写入

import { offlineOutbox } from '@happyvertical/smrt-web';

const products = createSmrtCollection(definition, {
  capabilities: [
    offlineOutbox({
      object: definition,
      namespace: {
        apiBase: '/api',
        tenantId,
        identityId: userId,
        manifestHash,
      },
      syncApplyBasePath: '/api',
    }),
  ],
});

IndexedDB出道盒通过生成的同步应用合同重放FIFO. 客户端 UUID 和 idepotent 严格插入对齐乐观行 创建第二个服务器身份。 Web 锁定会选出一个重播指挥 选项卡.

通过您自己的服务器操作进行离线写入

当一个模型生成的写动词因权限而关闭时 服务拥有其写规则,通过该操作重放而不是 sync/apply。通过 transport 改为 offlineOutbox() 用于收集或使用 offlineCommandQueue() 没有收藏的写法 :

import {
  dataSurfaceActionCommandTransport,
  offlineCommandQueue,
} from '@happyvertical/smrt-web';

const punches = offlineCommandQueue({
  name: 'clock_in',
  namespace, // the same DurableStoreKey as the app's other outboxes
  transport: dataSurfaceActionCommandTransport({
    transport: actionTransport, // the surface's online action transport
    request: (command) => ({
      identity: descriptor.identity,
      actionId: 'clock-in',
      expectedRevision: currentRevision(), // read at first replay, then pinned
      selection: { scope: 'current-page' },
      payload: command.payload,
    }),
  }),
});

const itemId = await punches.enqueue({ payload: { note } });
if (!itemId) {
  // Not captured durably (no IndexedDB): perform the action online instead.
}

每个回放都带有耐用性 idempotencyKey,该服务器 操作必须打开。 每条路由在自己的跨塔布下重放 FIFO 领导,有相同的后退和 pending → uploading → synced | failed 状态 机器。 机器。 。 重新装入的写入等待队列带有它的名字附加; 它是 从未改道 sync/apply。 。 。 .

清理共享设备的陈旧数据

listDurableNamespaces() 返回此浏览器的持久存储命名空间 持有(只有名称,没有内容) . pruneDurableNamespace(namespace, { olderThan }) 删除此命名空间的队列已下线, 并排入前 olderThan 联合国 Date 不挂起队列: 无重放, 无传送 仅限 { removed, skipped } 计数回来。 线路a上的项目 正在重放的活的队列( 在任意标签中) 被跳过 。 用它来变老 个人在共享硬件上排队的工作; 持续读取快照没有年龄 并留给 wipeDurableStore。 。 。 .

const cutoff = Date.now() - 7 * 24 * 60 * 60 * 1000;
for (const namespace of await listDurableNamespaces()) {
  await pruneDurableNamespace(namespace, { olderThan: cutoff });
}

已读缓存

persistCollection() 从索引化的 DB 快照启动温暖,然后重新验证 在背景中。 其命名空间包括API、租户、身份和清单 hash,因此用户开关和合同更改不能将另一个瞄准镜的行水合. 敏感收藏应省略这一能力.

persistDataSurface({ namespace, identity }) 对挂载数据所做的同样 表面,其行来自主范围查询,而不是生成 list 路径 : load() 在第一次接货之前, save(rows) 每次刷新之后. 它共享命名空间, 所以同样的擦擦干净它.

实时无效

创建一个全应用程序 createSmrtWebEventSubscriber() 和登记 liveInvalidation({ subscriber, tableName }) 每个收藏。 它会消耗 名称 _events SSE 框架和永久降级为 _changes 投票时间 SSE不可用或致命关闭。 授权和租赁 生成服务器读取路径; 信号不含行有效载荷 .

更新认识

createUpdateState() 将捆绑式的更新信号和合同显示信号结合起来. 斯维尔特适配器 useUpdateAvailable 连接到 SvelteKit 的更新商店 .

引擎边界

当前执行在内部使用 TanStack DB,但没有 @tanstack/* 类型可能在公共API中出现或生成声明。 应用程序必须 取决于 SmrtWebCollection 财务报告和审定财务报表 SmrtWebClient,保留引擎 可替换并阻止 Svelte 唯一的出口进入框架中性 核心键.

公共API团体

组主要出口
收款createSmrtCollection, (中文(简体) ), createSmrtWebClient, (中文(简体) ), newLocalId
远程查询createSmrtWebQuery, (中文(简体) ), SmrtWebQueryTransport
数据表面行动executeSmrtWebDataSurfaceAction, (中文(简体) ), SmrtWebDataSurfaceActionTransport, (中文(简体) ), dataSurfaceActionCommandTransport
HTTP 密码createDefinitionFetchers, (中文(简体) ), unwrapListResult, (中文(简体) ), unwrapItemResult
离线offlineOutbox, (中文(简体) ), offlineCommandQueue, (中文(简体) ), getOutboxHandle, (中文(简体) ), listDurableNamespaces, (中文(简体) ), pruneDurableNamespace
持久性persistCollection, (中文(简体) ), persistDataSurface, (中文(简体) ), wipeDurableStore
实时更新createSmrtWebEventSubscriber, (中文(简体) ), liveInvalidation
版本意识createUpdateState
网络MCPregisterWebMcpTools, (中文(简体) ), registerWebMcpBespokeTool, (中文(简体) ), registerViewIntent, (中文(简体) ), reserveWebMcpToolNames

WebMCP能力曝光

registerWebMcpTools() 默认安全: 省略曝光政策 仅登记 read 工具。 CRUD效应是固定的(list编号 :get 为: read, (中文(简体) ), create编号 :update 为: write,以及 delete 实值 destructive) (中文(简体) ). 自定义动作 未申报的元数据被视为具有破坏性、非理想性和开放性 这个世界 仅在路由元数据中宣布更安全的自定义动作语义 这些都是事实:

@smrt({
  api: {
    routes: {
      preview: {
        method: 'GET',
        effect: 'read',
        idempotent: true,
        openWorld: false,
      },
    },
  },
})
class Report extends SmrtObject {}

明确选择更广泛的能力. namespace 防止地表交叉 名称相撞, 明确 maxTools 链接所选集,并复制 名称或稳定的收集/行动身份 第一个浏览器注册。 不对全局适用隐含预算 改为注册 :

registerWebMcpTools(definitions, {
  effects: ['read', 'write', 'destructive'],
  namespace: 'admin',
  maxTools: 32,
  filter: (collection, tool) => collection.fields.tenantId !== undefined,
  filterTool: (tool) => tool.collection === 'reports',
});

返回的处置者还暴露了 ready 答应。 当宿主来临的时候 必须报告浏览器侧注册拒绝; 任何被拒绝的工具都会全部中止 之前那通电话的兄弟姐妹登记 ready 拒绝.

filter 接收遗留的收集元数据; filterTool 接收犬类 每工具定义。 在登记定义时只配置一个过滤器 对于其它过滤器类型, 关闭失败; 条形工具不携带完整 收集字段元数据,遗留的描述符不能满足词 过滤合同。 政策回调和获取器解析器获得孤立值 快照; 通过收藏/行动或工具等稳定值绘制关键主机侧图 名称,而不是定义对象身份.

不要将完整的遗产 和条理定义套装为相同的 藏书. 其重复的工具名称或收集/行动身份被拒绝 解剖注册。 优先选择完整生成的光圈集 涵盖范围,或只组成了脱节的后遗症和犬科子集.

宣布取消执行

铃声工具 execute(args, options) 接收主机的可选 WebMcpToolExecutionOptions 不变,包括 options.signal传出 向同步操作发出信号,并在发布结果前检查. 它代表了在登记之外取消这种援引 表示未注册工具。 现有的单参数调用和主机 删除选项仍然支持。 取消是合作的,不滚动 返回一个已经生效的操作.

使用相同的回调类型 smrt-svelte是因为 useWebMcpTool此转发 合同不为生成的REST或收集业务添加注销.

每个文档都锁定工具名称

生成的模型工具, 六个固定 smrt_ui_* 工具 UI 层登记册 在它自己的前缀下,宣布视图意图,以及手写铃声工具 独立生成名称, 全部结束于一个 document.modelContext。无 在宣布时间看到其他人,因为 namespace 一个UI prefix 为: 运行时间值 .

每个路径在浏览器之前通过一个文档全局锁定保留它的名称 看到它们,所以交叉路径的碰撞 被拒绝同步与一个 WebMcpToolNameCollisionError 指定工具名称和持有工具的所有人 (单位:千美元)generated, (中文(简体) ), ui, (中文(简体) ), intent,或 bespoke) (中文(简体) ). 浏览器用来拒绝 后来的登记和工具完全没有.

保留是一无所有, 处理注册 发布它的名字, 因此一个名称下的挂载/卸载/重挂循环继续工作. 用户界面 通过无依赖性登记其固定工具储备 @happyvertical/smrt-web/webmcp-tool-names 条目,通过相同的 document 写着 modelContext 从. 汇编已宣布视图意图的绑定 并登记在 registerWebMcpBespokeTool - 而不是通过 registerViewIntent ——通过 owner: 'intent' 因此,诊断名称 意图。 店主只是标签而已,却一文不值.

WebMCP 政策控制 网页广告的能力;它不是 授权边界。 执行仍然使用页面认证的 REST 运输,其认证、租赁、可写字的场地和敏感场地警卫必须 继续启用。 所有应用程序生成的工具结果都附加说明为不可信 内容,包括突变响应.

政策只缩小了生成的API元数据已经曝光的动作. 在收藏品外的遗物描述 actions 设定拒绝整个 注册,以及内在的 CRUD 效果不能被调用者数据重新标记.

移徙说明:以前依赖每个描述的登记 曝光现在必须通过 effects: ['read', 'write', 'destructive']优先选择 每个浏览器表面的更窄的允许列表 。 以前按键的集成 过滤器或解析器状态,根据定义,对象身份必须迁移到稳定 名称或收集/动作密钥。 如果既有遗产, 也有犬类定义阵列 可用, 在合并前选择一个完整的源或删除重叠 他们。 设定 maxTools (a) 明确显示需要硬性能力预算的表面; 溢出者拒绝完全登记,而不是截断登记.

发展

pnpm --filter @happyvertical/smrt-web test
pnpm --filter @happyvertical/smrt-web typecheck
pnpm --filter @happyvertical/smrt-web build

该建筑包括一个生成的 声明扫描 拒绝泄露的引擎 类型。 见 AGENTS.md 用于缓存、发件箱、SSE、持久性和 发动机的边际变化.

版本与发布记录

@happyvertical/smrt-web 共发布 323 个版本,首次发布于 2026/07/04;过去 12 个月发布了 323 个版本。

版本发布日期距今
0.62.1latest2026/11/17今天
0.62.02026/11/17今天
0.61.62026/11/161 天前
0.61.52026/11/161 天前
0.61.42026/11/161 天前
0.61.32026/11/152 天前

关于 @happyvertical/smrt-web 的常见问题

@happyvertical/smrt-web 是什么?

SMRT 浏览器客户端数据运行时间: 键入收集厂将客户端-数据引擎包入生成的 REST 客户端

如何安装 @happyvertical/smrt-web?

在项目目录运行 npm install @happyvertical/smrt-web,或使用 pnpm add / yarn add / bun add。

@happyvertical/smrt-web 支持 TypeScript 吗?

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

@happyvertical/smrt-web 支持 ESM 还是 CommonJS?

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

@happyvertical/smrt-web 可以商用吗?

@happyvertical/smrt-web 使用 未声明 许可。package.json 没有声明许可证。没有许可证的代码默认保留全部权利,商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括,不构成法律意见,请以许可原文为准。

@happyvertical/smrt-web 的下载量有多少?

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

@happyvertical/smrt-web 还在维护吗?

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