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

@mearl/daemon-core

v3.1.5

Published

Shared Node daemon lifecycle primitives for Mearl — process liveness, JSON record registry, log rotation, and a detached daemon manager

Readme

@mearl/daemon-core

简体中文 | English

Mearl 各 Node 包共享的守护进程生命周期原语:进程存活探测、JSON 记录注册表、日志滚动,以及一个 detached 守护进程管理器。

把 cloud-server、cloud-connector、native-host 里原本各写一份、容易彼此漂移的 daemon 逻辑(isAlive、原子读写注册表、日志滚动、按 key 派生路径)收敛到这一处,确保「写方」和「读方」对记录位置与格式始终一致。

此包只在 Node 中运行,可以作为普通依赖使用,也可以由执行宿主打包内联。

API

进程存活

isAlive(pid: number | undefined | null): boolean
isProcessGroupAlive(group: number): boolean

用 signal-0 探测进程是否存活(EPERM 视为存活——进程存在但属于他人)。Linux 同时读取 /proc/<pid>/stat,将已退出、尚未回收的 zombie 和 dead 状态视为已停止;主线程退出但仍有其他线程时,以及无法读取状态时,保守视为存活。

POSIX 进程组检查包含根进程退出后仍存活的后代。Linux 只有在两次检查得到相同的已退出成员及创建身份时,才确认组内执行已停止;活跃后代、成员变化和权限或读取失败都会保留清理未确认状态。Windows 不使用 POSIX 进程组检查。

路径派生(多实例)

DAEMON_HOME                                 // ~/.mearl
hashKey(key: string): string                // sha256(key) 前 16 位十六进制
keyedDir(subdir: string): string            // ~/.mearl/<subdir>
keyedConfigFile(subdir, key): string        // ~/.mearl/<subdir>/<hash>.json
keyedLogFile(subdir, key): string           // ~/.mearl/<subdir>/<hash>.log

多实例子系统(如按 serverUrl 区分的连接器)用这些 helper 派生每实例的文件路径。所有读写方都必须经由它们派生路径,这样彼此才不会对记录位置产生分歧。

记录注册表

interface DaemonRecord { pid: number; startedAt?: string; [k: string]: unknown }

ensureDir(dir: string): void
writeRecord(file: string, record: DaemonRecord): void   // 跨进程加锁,临时文件 + rename 原子写
claimRecord(file: string, record: DaemonRecord): boolean // 仅在文件不存在时原子占用
readRecord<T>(file: string): T | null
removeRecord(file: string): void
removeRecordIfPid(file: string, pid: number): boolean   // 仅删除指定进程仍拥有的记录
writeRecordIfPid(file: string, pid: number, record: DaemonRecord): boolean
removeInvalidRecord(file: string): boolean              // 清理无法解析的残留记录
listRecordFiles(dir: string): string[]                  // 目录下所有 *.json 绝对路径
readLiveRecords<T>(dir: string): T[]                    // 读取存活记录,并顺带清理死记录

守护进程管理器

createDaemon(opts: CreateDaemonOptions): Daemon

围绕一对 (configFile, logFile) 构建单实例守护进程管理器。start() 先原子占用启动锁, 再以 --foreground detached 方式拉起消费方 CLI,并立即写入带子进程 pid 的 starting 记录。子进程就绪后覆盖该记录,父进程据此确认启动完成。并发 start() 会复用正在启动或 已经运行的子进程。多实例子系统按实例 key 派生各自的 configFile / logFile。

interface CreateDaemonOptions {
  name: string;            // 日志标签,如 'CloudServer' / 'CloudConnector'
  scriptPath: string;      // 可重新拉起的 CLI 脚本绝对路径(消费方打包后的 cli.js)
  configFile: string;      // 本实例的 JSON 记录文件(由前台子进程写入)
  logFile: string;         // 本实例的日志文件
  foregroundArgs?: string[];   // 追加在 `--foreground` 之后的 argv
  readyTimeoutMs?: number;     // 等待子进程写记录的超时(默认 15000ms)
  formatInfo?: (record: DaemonRecord) => string | null;  // 起来后额外打印的信息
  startingRecord?: (pid: number, startedAt: string) => DaemonRecord;
}

interface Daemon {
  start(): Promise<void>;
  stop(expectedPid?: number): Promise<void>; // 指定 PID 时仅停止仍匹配的实例
  restart(): Promise<void>;
  status(): void;
  logs(lines?: number): void;
  running(): DaemonRecord | null;
}

scriptPath 必须是消费方自己的 cli.js:用打包进 cli 入口的某个模块里的 fileURLToPath(import.meta.url) 计算。daemon-core 自身被独立解析时,它的 import.meta.url 指向 daemon-core,而不是 cli。

日志

rotateLogIfNeeded(logFile: string, maxBytes?: number): void  // 超限则滚动为 <log>.1,默认 5MB
tailFile(logFile: string, lines: number): string

使用方

  • cloud-server —— createDaemon(单实例,~/.mearl/cloud-server.json)
  • cloud-connector —— createDaemon(多实例,按 serverUrl 区分,~/.mearl/connectors/<hash>.json)+ readLiveRecords 列举
  • native-host —— 仅用原语(isAlive / keyedConfigFile / readRecord / readLiveRecords 等)读取连接器共享注册表,以发现/接管/列举连接器

@mearl/daemon-core/capabilities 的 NodeCapabilityRegistry 可在第三个构造参数传入 hooks,只加载这些绑定引用的模块。选择本身仍完整校验,目标模块字节按摘要验证,提交仍核对当前选择;忽略的模块不执行。该局部实例适用于安装 CLI 等只需要少量本机服务的宿主,不替代完整 Native Host 的激活与就绪回执。省略 hooks 时保持完整加载。