@rayvision/refresh-manager

@rayvision/refresh-manager is a lightweight polling manager for browser applications. It supports:

• keyed refresh subscriptions
• persisted snapshots in localStorage
• central interval config polling
• both JavaScript and TypeScript consumers

Install

yarn add @rayvision/refresh-manager

Usage

import { initRefreshManager } from "@rayvision/refresh-manager";

const REFRESH_KEYS = {
  LOGGER: "logger-clean",
} as const;

const manager = initRefreshManager({
  query(key) {
    return fetch(`/api/refresh?key=${encodeURIComponent(String(key))}`).then(
      (response) => response.json()
    );
  },
});

manager.register(REFRESH_KEYS.LOGGER, (nextSnapshot) => {
  console.info(nextSnapshot.value);
});

manager.start();

Init Options

initRefreshManager(options) 支持这些初始化配置项：

• query 必填。类型：(key: RefreshQueryKeyInput) => Promise<RefreshQueryResult> | RefreshQueryResult。 用于统一拉取两类数据：

  1. 间隔配置本身 intervalConfigKey
  2. 各业务 key 对应的数据

• intervalConfigKey 可选。类型：string。 用于指定“刷新配置表”的查询 key。 默认值：'interval-config-key'

• intervalConfigRefreshInterval 可选。类型：number。 用于指定刷新配置表自身的最小轮询间隔，单位毫秒。 当服务端返回的顶层 interval 大于 0 且小于这个值时，会被自动提升到这个最小值。 如果服务端返回顶层 interval = 0，则停止配置表轮询，但保留当前返回的 configMap 继续驱动业务 key； 返回 interval = -1 时停止配置表轮询，并忽略 configMap 中的业务 key。 默认值：5 * 60 * 1000

• minRefreshInterval 可选。类型：number。 用于限制业务 key 的最小刷新间隔，单位毫秒。 当服务端返回的 interval 小于这个值时，会被自动提升到这个最小值。 默认值：30 * 1000

• onError 可选。类型：(error: unknown, context: RefreshContext) => void。 当查询配置或刷新业务 key 发生异常时触发。 当前 context 内包含：

  • key: 当前请求的 key

• storageKeyPrefix 可选。类型：string。 用于自定义本地 localStorage 的 key 前缀，避免和其他业务冲突。 默认值：'refresh-manager:'

The package publishes:

• dist/index.cjs for CommonJS consumers
• dist/index.mjs for ESM consumers
• dist/index.d.ts for TypeScript declarations

Tool Runtime

The package also provides a configurable browser tool runtime:

import { mountRefreshManagerTool } from "@rayvision/refresh-manager/tool";

mountRefreshManagerTool(document.getElementById("app"), {
  envOptions: [
    {
      id: "test",
      label: "测试环境",
      intervalConfigKey: "BEM-test",
      headers: {},
    },
    {
      id: "prod",
      label: "生产环境",
      intervalConfigKey: "BEM-prod",
      headers: {},
    },
  ],
  registeredRules: [
    {
      prefix: "BEM",
      rules: [
        {
          key: "logger-clean",
          source: "src/utils/logger-report.js",
          notes: ["value 期望包含 updateTime。"],
        },
      ],
    },
  ],
  queryPath: "/api/query",
  notifyPath: "/api/notify",
});

When used in a local static tool page, you can keep the project-side webpack proxy and only pass relative API paths into the tool runtime.

The interval-config response shape is:

{
  "debug": false,
  "interval": 300000,
  "configMap": {
    "logger-clean": {
      "interval": 0,
      "updateTime": 1710000000000
    }
  }
}

Top-level interval has its own control semantics for config polling:

• interval = -1: stop config polling and ignore configMap
• interval = 0: stop config polling, but keep the current configMap active for business keys
• interval > 0: poll by that interval, with intervalConfigRefreshInterval as the minimum