@zucker-framework/provider 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,410 @@
+/**
+ * A named provider instance with optional metadata.
+ * @template T - The type of the provided instance
+ */
+interface Provider<T> {
+    /** Unique identifier for this provider */
+    id: string;
+    /** The provider instance */
+    instance: T;
+    /** Optional metadata associated with this provider */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Disposable handle returned by register — call dispose() to unregister.
+ * Mirrors Java Reactor Disposable pattern used in jetlinks Provider.
+ */
+interface Disposable {
+    dispose(): void;
+}
+/**
+ * Registry for managing named provider instances.
+ * Supports registration, lookup, default provider, and register-if-absent patterns.
+ * @template T - The type of the provided instances
+ */
+interface ProviderRegistry<T> {
+    /** Register a provider; returns a Disposable to unregister it later. */
+    register(provider: Provider<T>): Disposable;
+    unregister(id: string): void;
+    get(id: string): Provider<T> | undefined;
+    /** Get provider by id; throws if not found. Mirrors Java Provider.getNow(). */
+    getNow(id: string): Provider<T>;
+    getAll(): Provider<T>[];
+    getDefault(): Provider<T> | undefined;
+    setDefault(id: string): void;
+    /**
+     * Register if absent — returns the existing provider if one is already
+     * registered under the same id, otherwise registers and returns undefined.
+     * Mirrors Java Provider.registerIfAbsent().
+     */
+    registerIfAbsent(provider: Provider<T>): Provider<T> | undefined;
+    /**
+     * Register if absent with a builder function.
+     * Mirrors Java Provider.registerIfAbsent(id, Function).
+     */
+    registerIfAbsentWith(id: string, builder: (id: string) => Provider<T>): Provider<T> | undefined;
+}
+declare class DefaultProviderRegistry<T> implements ProviderRegistry<T> {
+    private readonly logger;
+    private providers;
+    private defaultId;
+    private hooks;
+    register(provider: Provider<T>): Disposable;
+    unregister(id: string): void;
+    get(id: string): Provider<T> | undefined;
+    /**
+     * Get provider by id; throws if not found.
+     * Mirrors Java SimpleProvider.getNow() which throws BusinessException.
+     */
+    getNow(id: string): Provider<T>;
+    getAll(): Provider<T>[];
+    getDefault(): Provider<T> | undefined;
+    setDefault(id: string): void;
+    /**
+     * Register if absent — if a provider with the same id already exists,
+     * returns the old provider and skips registration. Otherwise registers
+     * the new provider and returns undefined.
+     * Mirrors Java SimpleProvider.registerIfAbsent(id, T).
+     */
+    registerIfAbsent(provider: Provider<T>): Provider<T> | undefined;
+    /**
+     * Register if absent using a builder function.
+     * Mirrors Java SimpleProvider.registerIfAbsent(id, Function<String, T>).
+     */
+    registerIfAbsentWith(id: string, builder: (id: string) => Provider<T>): Provider<T> | undefined;
+    addHook(hook: RegistryHook<T>): Disposable;
+    removeHook(hook: RegistryHook<T>): void;
+}
+/**
+ * Lifecycle hook for ProviderRegistry events.
+ * Allows reacting to provider registration and unregistration.
+ * @template T - The type of the provided instances
+ */
+interface RegistryHook<T> {
+    /** Called when a new provider is registered */
+    onRegister?(provider: Provider<T>): void;
+    /** Called when a provider is unregistered */
+    onUnregister?(provider: Provider<T>): void;
+}
+
+/**
+ * Base interface for a named strategy.
+ */
+interface Strategy {
+    /** Unique identifier for this strategy */
+    id: string;
+}
+/**
+ * Manager for registering and resolving named strategies.
+ * @template S - The strategy type
+ */
+interface StrategyManager<S extends Strategy> {
+    register(strategy: S): void;
+    unregister(id: string): void;
+    get(id: string): S | undefined;
+    /** Get a strategy by id; throws if not found. */
+    getNow(id: string): S;
+    getAll(): S[];
+    /** Check if a strategy is registered. */
+    has(id: string): boolean;
+}
+/**
+ * Default strategy manager — mirrors Java StaticStrategyManager with
+ * doWith helpers and onStrategyNotFound hook.
+ */
+declare class DefaultStrategyManager<S extends Strategy> implements StrategyManager<S> {
+    private readonly logger;
+    private strategies;
+    register(strategy: S): void;
+    unregister(id: string): void;
+    get(id: string): S | undefined;
+    /**
+     * Get strategy by id; throws if not found.
+     * Mirrors Java StaticStrategyManager's implicit throw behaviour via
+     * switchIfEmpty + onStrategyNotFound.
+     */
+    getNow(id: string): S;
+    getAll(): S[];
+    /**
+     * Check if a strategy is registered.
+     */
+    has(id: string): boolean;
+    /**
+     * Execute an async function with a resolved strategy.
+     * Mirrors Java StaticStrategyManager.doWithMono().
+     */
+    doWith<T>(strategyId: string, executor: (strategy: S) => Promise<T>): Promise<T | undefined>;
+    /**
+     * Execute an async function that returns an array with a resolved strategy.
+     * Mirrors Java StaticStrategyManager.doWithFlux().
+     */
+    doWithMany<T>(strategyId: string, executor: (strategy: S) => Promise<T[]>): Promise<T[]>;
+    /**
+     * Called when a strategy is not found. By default throws an error.
+     * Subclasses can override to return a fallback or silently return undefined.
+     * Mirrors Java StaticStrategyManager.onStrategyNotFound().
+     */
+    protected onStrategyNotFound(strategyId: string): never;
+}
+
+/**
+ * Lifecycle hook interface for reacting to registration/unregistration events.
+ * @template T - The type of the managed item
+ */
+interface LifecycleHook<T> {
+    /** Called when an item is registered */
+    onRegister?(item: T): void | Promise<void>;
+    /** Called when an item is unregistered */
+    onUnregister?(item: T): void | Promise<void>;
+}
+/**
+ * Manager for lifecycle hooks — fires register/unregister events to all registered hooks.
+ * @template T - The type of the managed item
+ */
+declare class HookManager<T> {
+    private hooks;
+    /**
+     * Add a lifecycle hook.
+     * @param hook - The hook to add
+     */
+    addHook(hook: LifecycleHook<T>): void;
+    /**
+     * Remove a previously added lifecycle hook.
+     * @param hook - The hook to remove
+     */
+    removeHook(hook: LifecycleHook<T>): void;
+    /**
+     * Fire the onRegister event on all hooks.
+     * @param item - The item being registered
+     */
+    fireRegister(item: T): Promise<void>;
+    /**
+     * Fire the onUnregister event on all hooks.
+     * @param item - The item being unregistered
+     */
+    fireUnregister(item: T): Promise<void>;
+    /**
+     * Get a copy of all registered hooks.
+     * @returns An array of registered lifecycle hooks
+     */
+    getHooks(): LifecycleHook<T>[];
+}
+
+/**
+ * 组合 Provider — 按优先级聚合多个同类 Provider，
+ * 参考 jetlinks CompositeNotifyConfigManager 的 switchIfEmpty 语义。
+ */
+declare class CompositeProvider<T> {
+    private readonly logger;
+    private readonly providers;
+    constructor(providers?: T[]);
+    /**
+     * 添加一个 provider（追加到末尾，优先级最低）
+     */
+    add(provider: T): void;
+    /**
+     * 在指定位置插入 provider（索引越小优先级越高）
+     */
+    addFirst(provider: T): void;
+    /**
+     * 按优先级依次尝试所有 provider，返回首个非空结果（switchIfEmpty 语义）
+     */
+    get<R>(fn: (provider: T) => R | undefined | null | Promise<R | undefined | null>): Promise<R | undefined>;
+    /**
+     * 合并所有 provider 的结果并去重
+     * @param fn 从每个 provider 获取数组结果
+     * @param keyFn 可选的去重 key 提取函数
+     */
+    getAll<R>(fn: (provider: T) => R[] | Promise<R[]>, keyFn?: (item: R) => string): Promise<R[]>;
+    /**
+     * 按优先级执行直到成功（switchIfEmpty 语义）
+     * 如果某个 provider 抛错则跳过，尝试下一个
+     */
+    execute<R>(fn: (provider: T) => Promise<R>): Promise<R>;
+    /**
+     * 移除指定 provider
+     * @returns true if the provider was found and removed
+     */
+    remove(provider: T): boolean;
+    getProviders(): readonly T[];
+    get size(): number;
+}
+
+/**
+ * 支持 fallback 的 ProviderRegistry — 在找不到指定 provider 时，
+ * 按备选 ID 列表依次查找，或返回默认 provider。
+ */
+declare class FallbackProviderRegistry<T> implements ProviderRegistry<T> {
+    private readonly logger;
+    private readonly delegate;
+    register(provider: Provider<T>): Disposable;
+    unregister(id: string): void;
+    get(id: string): Provider<T> | undefined;
+    getNow(id: string): Provider<T>;
+    registerIfAbsent(provider: Provider<T>): Provider<T> | undefined;
+    registerIfAbsentWith(id: string, builder: (id: string) => Provider<T>): Provider<T> | undefined;
+    getAll(): Provider<T>[];
+    getDefault(): Provider<T> | undefined;
+    setDefault(id: string): void;
+    /**
+     * 按序查找 provider：先找主 ID，找不到则依次尝试 fallback ID 列表
+     */
+    getWithFallback(id: string, ...fallbackIds: string[]): Provider<T> | undefined;
+    /**
+     * 找不到指定 ID 的 provider 时返回默认 provider
+     */
+    getOrDefault(id: string): Provider<T> | undefined;
+}
+
+declare const PROVIDER_REGISTRY: unique symbol;
+declare const STRATEGY_MANAGER: unique symbol;
+declare class ZuckerProviderModule {
+}
+
+/**
+ * 资源提供者 SPI
+ */
+interface ResourceProvider {
+    /** 获取资源类型标识 */
+    getType(): string;
+    /** 根据 ID 获取资源实例 */
+    getResource(id: string): Promise<unknown>;
+    /** 列出所有可用资源 ID */
+    listResources?(): Promise<string[]>;
+}
+/**
+ * 资源管理器 — 按 type + id 获取资源
+ */
+declare class ResourceManager {
+    private readonly logger;
+    private providers;
+    /** 注册资源提供者 */
+    registerProvider(provider: ResourceProvider): void;
+    /** 注销资源提供者 */
+    unregisterProvider(type: string): void;
+    /**
+     * 根据类型和 ID 获取资源（不存在时返回 undefined）
+     * @param type 资源类型
+     * @param id 资源 ID
+     * @returns 资源实例或 undefined
+     */
+    getResource<T = unknown>(type: string, id: string): Promise<T | undefined>;
+    /**
+     * 根据类型和 ID 获取资源（不存在时抛出 NotFoundException）
+     * @param type 资源类型
+     * @param id 资源 ID
+     * @returns 资源实例
+     * @throws NotFoundException 资源不存在时
+     */
+    getResourceOrThrow<T = unknown>(type: string, id: string): Promise<T>;
+    /** 获取指定类型的资源提供者 */
+    getProvider(type: string): ResourceProvider | undefined;
+    /** 获取所有已注册的资源类型 */
+    getTypes(): string[];
+}
+
+/**
+ * 从项目目录的 JSON 文件加载资源
+ */
+declare class ClasspathResourceProvider implements ResourceProvider {
+    private readonly type;
+    private readonly basePath;
+    constructor(type: string, basePath: string);
+    getType(): string;
+    getResource(id: string): Promise<any>;
+    listResources(): Promise<string[]>;
+}
+
+/**
+ * 从文件系统加载资源（支持任意文件类型）
+ */
+declare class FileResourceProvider implements ResourceProvider {
+    private readonly type;
+    private readonly basePath;
+    private readonly extension;
+    constructor(type: string, basePath: string, extension?: string);
+    getType(): string;
+    getResource(id: string): Promise<Buffer | undefined>;
+    listResources(): Promise<string[]>;
+}
+
+/**
+ * Provider 健康检查扩展
+ *
+ * 对标 Claude Code Plugin 系统的 manifest validation + health checks:
+ * 对已注册的 Provider 进行周期性健康检查和条件激活。
+ */
+interface HealthCheckable {
+    /** 执行健康检查，返回 true 表示健康 */
+    healthCheck(): Promise<boolean>;
+}
+interface ConditionalProvider {
+    /** 判断该 Provider 是否应该被激活 */
+    shouldActivate(): boolean | Promise<boolean>;
+}
+type HealthStatus = 'healthy' | 'unhealthy' | 'unknown';
+interface ProviderHealthInfo {
+    id: string;
+    status: HealthStatus;
+    lastChecked: number;
+    consecutiveFailures: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Provider 健康检查管理器
+ *
+ * 用法:
+ * ```ts
+ * const healthManager = new ProviderHealthManager(registry);
+ *
+ * // 对所有支持健康检查的 Provider 执行检查
+ * const results = await healthManager.checkAll();
+ *
+ * // 启动定期检查
+ * healthManager.startPeriodicChecks({ intervalMs: 30_000 });
+ *
+ * // 停止检查
+ * healthManager.stop();
+ * ```
+ */
+declare class ProviderHealthManager<T> {
+    private readonly registry;
+    private readonly logger;
+    private readonly healthState;
+    private intervalHandle?;
+    constructor(registry: ProviderRegistry<T>);
+    /**
+     * 对所有已注册的 Provider 执行健康检查
+     */
+    checkAll(): Promise<ProviderHealthInfo[]>;
+    /**
+     * 对单个 Provider 执行健康检查
+     */
+    check(provider: Provider<T>): Promise<ProviderHealthInfo>;
+    /**
+     * 获取所有 Provider 的健康状态
+     */
+    getHealthStatus(): ProviderHealthInfo[];
+    /**
+     * 获取只包含健康 Provider 的列表
+     */
+    getHealthyProviders(): Provider<T>[];
+    /**
+     * 启动定期健康检查
+     */
+    startPeriodicChecks(options: {
+        intervalMs: number;
+    }): void;
+    /**
+     * 停止定期健康检查
+     */
+    stop(): void;
+    /**
+     * 检查 Provider 是否应该被激活（条件激活）
+     */
+    shouldActivate(provider: Provider<T>): Promise<boolean>;
+    private isHealthCheckable;
+    private isConditional;
+}
+
+export { ClasspathResourceProvider, CompositeProvider, type ConditionalProvider, DefaultProviderRegistry, DefaultStrategyManager, type Disposable, FallbackProviderRegistry, FileResourceProvider, type HealthCheckable, type HealthStatus, HookManager, type LifecycleHook, PROVIDER_REGISTRY, type Provider, type ProviderHealthInfo, ProviderHealthManager, type ProviderRegistry, type RegistryHook, ResourceManager, type ResourceProvider, STRATEGY_MANAGER, type Strategy, type StrategyManager, ZuckerProviderModule };