npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@mzzsfy/dsh-common-tools

v0.5.1

Published

全家桶公共依赖库:按插件空间隔离的 WebSocket 双向订阅/推送与 toast;host setupCommonTools 借消费插件生命周期激活,client 复用页面单连接;普通 npm 依赖而非 dsh 插件

Readme

@mzzsfy/dsh-common-tools

公共依赖库,提供插件独立消息通道与 toast。普通 npm 包,不是 DSH 插件。host 与 client 都通过当前插件的 ctx 建立通道,插件名自动来自 loader 的 ctx.fiber.entry.options.name,使用完整 npm 包名。共享模块的 require 不携带调用者身份,必须在 apply(ctx) 中初始化。

双接口

两端 API 相同,消息就是业务 payload:

const bus = setupCommonTools(ctx)
const stop = bus.subscribe(message => handleMessage(message))
bus.publish({ type: 'refresh' })

host:

import { setupCommonTools } from '@mzzsfy/dsh-common-tools/host'
export const inject = ['webServer']
export function apply(ctx) {
  const bus = setupCommonTools(ctx)
  bus.subscribe(message => handleCommand(message))
  bus.publish({ changed: true })
}

client:

window.__ModuleLoader__.load({
  id: '@mzzsfy/example', // 与 host 的包名一致
  factory(require) {
    const { setupCommonTools, createSnapshotRefresh, toast } = require('@mzzsfy/dsh-common-tools/client')
    return {
      apply(ctx) {
        const bus = setupCommonTools(ctx)
        const controller = new AbortController()
        const snapshot = createSnapshotRefresh(async () => {
          const res = await fetch('/api/example/snapshot', { signal: controller.signal })
          const data = await res.json()
          if (!controller.signal.aborted) console.log(data)
        })
        bus.subscribe(snapshot.refresh, { onReset: snapshot.refresh })
        ctx.effect(() => () => { snapshot.dispose(); controller.abort() })
        ctx.effect(() => {
          const button = document.createElement('button')
          button.textContent = '刷新'
          button.onclick = () => {
            try { bus.publish({ type: 'refresh' }) }
            catch (error) { toast.show(error.message, { kind: 'error' }) }
          }
          document.body.appendChild(button)
          return () => button.remove()
        })
      },
    }
  },
})

示例中的快照路由与 host 命令处理由消费插件实现;示例按钮展示发送与卸载接线,实际插件可换成已注册面板。消费方仍需声明依赖与 external,见下文装载说明。

| 方法 | 行为 | |---|---| | subscribe(listener) | 接收对端本插件消息,listener(payload),返回幂等退订函数 | | publish(payload = null) | 向对端本插件发送 JSON 消息,上行不自动广播回来 | | client subscribe(listener, { onReset }) | 可选恢复回调,接收订阅确认后对账,首连/重连均触发 | | host onPresence(listener) | 接收本插件的浏览器连接数;注册立即回调,变化时回调,返回退订函数 |

插件本身就是通道,没有 topic 和消息版本。不同插件不能通过本门面指定别人的空间;同插件多实例共享空间。业务需要区分消息时直接使用 payload 中的业务字段。回调同步抛错或异步拒绝均告警隔离。

生命周期

client 初始化取得插件实例的连接使用权;纯发送插件不需要制造接收订阅。组件提前退订仅停止接收,不影响发送。插件卸载自动清理自己的全部订阅和使用权,最后一个实例卸载才关闭页面共享 WS、取消重连。host 同样按实例清理,最后一个 host 使用方退出删除路由、连接和心跳。

presence 只统计有接收订阅的连接,纯发送实例不计在场。对已就绪空间新增订阅时,onReset 在 subscribe 返回前同步执行。尚未确认的订阅不接收业务消息,遗漏由随后的快照对账恢复。

连接与边界

页面全部插件共享 WS /api/bus/ws;HTTPS 自动使用 WSS,不占 HTTP/1.1 普通请求连接池。首连/重连完成接收确认后调用 onReset 拉业务快照,不做事件重放。总线逐条交付 payload,不合并业务消息。五个快照消费方在宿主合并失效广播、在客户端单飞刷新,持续变更下同一刷新器的起始间隔至少一秒;首次立即,窗口内变更在末尾补拉。cron 的偏好与看板共用 status 请求。

断开后指数退避加抖动重连,上限 30 秒,握手确认超时 10 秒。服务端每 30 秒 ping,未回复的连接终止。单帧及发送积压上限 1 MiB,按完整 JSON 协议消息 UTF-8 字节计算;非法 JSON payload 或超界发送同步拒绝,慢接收方积压超界断开。publish 交给本地 WS 即返回,不表示业务处理完成;断线不排队、不自动重发。

快照消费方可独立使用 host 导出的 createChangeNotifier(() => bus.publish()) 与 client 导出的 createSnapshotRefresh(loadSnapshot)。两者返回 { refresh, dispose },与实例生命周期一起释放。前者仅合并失效通知;后者保证单飞及末尾补拉,失败不会自行形成重试循环,调用方仍负责请求超时和迟到响应检查。调度采用正常系统时钟下的一秒窗口,空闲时无定时轮询。

内部协议

| 方向 | 帧 | |---|---| | client → host | { "type": "hello", "protocol": 1, "version": "<包版本>" } | | host → client | { "type": "hello", "protocol": 1, "protocols": [1], "version": "<包版本>" } | | client → host | { "type": "subscribe", "plugins": ["@mzzsfy/dsh-tunnel"], "revision": 1 } | | host → client | { "type": "ready", "plugins": ["@mzzsfy/dsh-tunnel"], "revision": 1 } | | client → host | { "type": "publish", "plugin": "@mzzsfy/dsh-tunnel", "payload": {} } | | host → client | { "type": "message", "plugin": "@mzzsfy/dsh-tunnel", "payload": {} } |

订阅帧替换接收空间清单,与发送资格无关。revision 仅协调接收确认,不是业务消息版本。非法帧或二进制上行关闭连接;明确跨源上行写入被拒绝,身份认证及可达性由宿主承担,不设插件认证层。

host 的 WS 实现多实体以进程级注册表共享传输,同版不重复安装,较新版本接管传输并保留监听;已有 WS 门面动态转发。upgrade 不经宿主 /api prefix 闸门(responder 只按 exact pathname 分发),交付 socket 前自行回问一次 connection.requestRejection,非空即写状态码并断 socket;connection 服务缺失时放行,与插件 HTTP 路由同口径。缺少 registerUpgrade 时告警并停用总线,不注册资源。loader 上下文缺少包名时明确拒绝,不猜测身份。0.2.0 移除旧 SSE、topic、forPlugin 和 version 接口,无兼容路径。升级须统一更新消费方与依赖,完整重启宿主并刷新旧页面;旧代际 SSE(包 0.1)与 WS 代际(注册版本:0.2-0.3 写死 1.0,0.4.0 起与包版本同锁)同进程混装会发生注册表冲突,不支持跨该代际热接管。

兼容窗口与版本协商

当前窗口 0.5.x:帧集合、导出形状与 setupCommonTools 门面语义在 0.5.x 内保持向后兼容,只允许发 patch。0.6.0 视为破坏性版本(0.x 语义里 minor 即破坏),必须与十个消费方的依赖范围抬升同批发布——npm 的 ^0.5.0 只约束安装,装载行按包名取 profile 顶层那份,单独发 0.6.0 会被 hoist 给仍在 ^0.5.0 的旧插件。窗口与红线见 DEVELOPMENT/client-dependency.md。

0.4.x → 0.5.0 的实际增量:client 新增导出 Tooltip 与 tipPlacement(见「悬浮提示」),host 侧 WS upgrade 补一次宿主闸门回问;既有帧集合、门面与 toast 语义未变。

版本协商:client 连接首帧上报 { type: 'hello', protocol: 1, version },host 回 { type: 'hello', protocol, protocols: [1], version }。协议无交集时 client 打印一条告警并关闭连接、不再重连(页级总线停用);旧 host(0.3.x 及以前)把未知帧当非法帧直接关连接,client 在 hello 宽限窗内被关即判定为老帧模式,降级为不报版本重连一次,连接从未 open 就断开不触发降级。帧协议改动即递增 PROTOCOL;host 侧 PKG_VERSION 与包版本同锁(仓库测试守)。

装载与 Toast

client 模块由每个消费插件自带的装载行进入宿主:消费方在自己的 cordis.patch.yml 里加一行 id: <本包前缀>-dsh-common-tools、name: '@mzzsfy/dsh-common-tools'。宿主按包名把多行合并成一份 client 模块(entriesByName + compose),bundle 只拼一次、模块只注册一次,多行在宿主侧是多个空 apply() 条目;本包不 host 别人的行,也不依赖别人 host 自己的行——装任一消费插件即可独立运行。消费方声明 dependencies(范围 ^0.5.0)与 external @mzzsfy/dsh-common-tools/client,factory 内 require 后经命名空间使用;该包须能从 profile 根解析,生产 profile 为 pnpm nodeLinker: hoisted。装载规约见 DEVELOPMENT/client-dependency.md。toast 不要求建立 bus:

const { toast } = require('@mzzsfy/dsh-common-tools/client')
toast.show('已归档', { kind: 'ok' })
toast.show('任务完成\n耗时 12 秒', { appearance: 'panel', holdMs: 6000 })

自 0.3.0 起,appearance 支持 toast(默认,宿主 toast-bg/toast-label 色对)与 panel(宿主 bg-layer-1/label-primary 色对)。两种样式随宿主亮暗主题更新,成功/错误只强调边框,不覆盖底色或文案颜色;多行文本保留换行。未知值使用 toast,设置仅作用于本条通知。kind 支持 info/ok/error,sticky: true 常驻并显示“知道了”,onClick 点击直达,holdMs 指定自动消失时间(默认 4 秒)。

悬浮提示

client 侧通用悬浮提示(0.5.0 起),消费方只给锚点与内容:

const { Tooltip } = require('@mzzsfy/dsh-common-tools/client')

h(Tooltip, { anchor }, content)
  • anchor 两种形态:指针 { kind: 'point', x, y }(悬停时给,组件在 mousemove 上跟随)与元素矩形 { left, top, width, height }(快照,页面滚动后自动收起)。
  • panelSelector 可选:给定时以该面板矩形为夹取边界,提示不飘出弹窗;缺省用视口。
  • 定位:上下越界换侧,两侧都放不下取空间大的一侧再夹取进边界;元素锚点画箭头,指针锚点不画。
  • 渲染:portal 到 body,样式类 dct-tip* 随 toast 样式表注入(首次使用前经 layout effect 注入,不依赖是否发过 toast);宿主模块表缺 react-dom 主入口时降级就地渲染,提示仍可见。
  • tipPlacement 一并导出(纯函数:(anchor, tipSize, bounds, options) → { left, top, side, arrowX }),供消费方在不挂组件时复用同一套定位规则。

测试

在本包目录执行:

npm install --omit=peer
node --test "test/*.test.mjs"

覆盖范围见兼容性测试。