@quickbi/bi-revisal-core

数据订正核心引擎。零业务依赖、无副作用、sideEffects: false。

提供泛型的同步/异步订正管线，按版本号顺序链式执行 guard 函数，将数据结构从旧版本升级到新版本。

API

// 类型
type Guard<T, C = void> = (data: T, ctx: C) => T | Promise<T>;
interface ChangeLog<T, C = void> {
  version: string;
  guards: Array<Guard | LazyLoader>;
}
interface ReviseOptions<T, C = void> {
  onError?;
  filter?;
}

// 同步引擎 — guards 必须全是同步纯函数
function revise<T, C>(data, currentVersion, changeLogs, ctx?, options?): T;

// 异步引擎 — 支持 lazy import + 同步 guard 混合
function reviseAsync<T, C>(data, currentVersion, changeLogs, ctx?, options?): Promise<T>;

// 工具
function getRevisalRange<T, C>(version, changeLogs): ChangeLog[];
function computeLatestVersion<T, C>(changeLogs, fallbackVersion?): string;

onError 策略

| 值 | 行为 | | --------- | ------------------------------------------------------------------------- | | 'throw' | 默认，guard 抛错向上抛出 | | 'skip' | 吞掉错误，原值透传，后续 guard 继续执行 | | 函数 | 自定义处理，接收 (err, { data, version, guardIndex }) 返回修正后的 data |

用法 1: 同步纯函数 guard

适用于自定义组件 meta 等纯数据结构的订正。

import { revise, computeLatestVersion, ChangeLog } from '@quickbi/bi-revisal-core';

interface MyMeta {
  /* ... */
}

const CHANGE_LOGS: ChangeLog<MyMeta>[] = [
  {
    version: '4.1',
    guards: [meta => ({ ...meta, newField: 'value' })],
  },
];

export const revisal = (meta: MyMeta, version: string) => revise(meta, version, CHANGE_LOGS);

export const LATEST_VERSION = computeLatestVersion(CHANGE_LOGS, '4.0.3');

用法 2: 异步懒加载 guard

适用于需要按需加载 guard 模块（代码分割）的场景。

import { reviseAsync, ChangeLog, Guard } from '@quickbi/bi-revisal-core';

interface Snapshot {
  /* ... */
}

// 本地适配: 将类约定转为纯函数 guard
function wrapClassGuard(loader: () => Promise<{ default: new () => MyGuard }>) {
  return async (snapshot: Snapshot) => {
    const { default: GuardClass } = await loader();
    const g = new GuardClass();
    return g.reviser(snapshot);
  };
}

const CHANGE_LOGS: ChangeLog<Snapshot>[] = [
  {
    version: '5.1',
    guards: [wrapClassGuard(() => import('./guards/5.1/root')), wrapClassGuard(() => import('./guards/5.1/query'))],
  },
];

export const reviseSnapshot = (snapshot: Snapshot, version: string) =>
  reviseAsync(snapshot, version, CHANGE_LOGS, undefined, { onError: 'skip' });

设计原则

• core 只认幂等的 guard 函数，不感知任何业务概念（组件类型、类构造、谓词匹配等）
• 业务层的特殊约定（懒加载、类实例化、过滤匹配）统一在适配函数中处理
• revise 严格同步：guard 返回 Promise 或包含 lazy loader 时 throw
• reviseAsync 兼容同步 guard，可混合使用