@h-ai/scheduler 0.1.0-alpha5

package/dist/index.d.ts

@@ -0,0 +1,364 @@
+import { z } from 'zod';
+import * as _h_ai_core from '@h-ai/core';
+import { PaginationOptionsInput, HaiResult, PaginatedResult } from '@h-ai/core';
+
+/**
+ * @h-ai/scheduler — 配置 Schema
+ *
+ * 本文件定义定时任务模块的配置结构，使用 Zod 进行运行时校验。
+ * @module scheduler-config
+ */
+
+/**
+ * 调度器配置 Zod Schema
+ *
+ * 所有字段均可选，提供合理默认值。
+ *
+ * @example
+ * ```ts
+ * const config = SchedulerConfigSchema.parse({
+ *   enableDb: true,
+ *   tickInterval: 1000,
+ * })
+ * ```
+ */
+declare const SchedulerConfigSchema: z.ZodObject<{
+    enableDb: z.ZodDefault<z.ZodBoolean>;
+    tickInterval: z.ZodDefault<z.ZodNumber>;
+    lockExpireMs: z.ZodDefault<z.ZodNumber>;
+    nodeId: z.ZodOptional<z.ZodString>;
+    maxLogs: z.ZodOptional<z.ZodNumber>;
+    retentionDays: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** 调度器配置类型 */
+type SchedulerConfig = z.infer<typeof SchedulerConfigSchema>;
+/** 调度器配置输入类型 */
+type SchedulerConfigInput = z.input<typeof SchedulerConfigSchema>;
+
+declare const HaiSchedulerError: {
+    readonly NOT_INITIALIZED: _h_ai_core.HaiErrorDef;
+    readonly INIT_FAILED: _h_ai_core.HaiErrorDef;
+    readonly CONFIG_ERROR: _h_ai_core.HaiErrorDef;
+    readonly TASK_NOT_FOUND: _h_ai_core.HaiErrorDef;
+    readonly TASK_ALREADY_EXISTS: _h_ai_core.HaiErrorDef;
+    readonly INVALID_CRON: _h_ai_core.HaiErrorDef;
+    readonly EXECUTION_FAILED: _h_ai_core.HaiErrorDef;
+    readonly JS_EXECUTION_FAILED: _h_ai_core.HaiErrorDef;
+    readonly API_EXECUTION_FAILED: _h_ai_core.HaiErrorDef;
+    readonly DB_SAVE_FAILED: _h_ai_core.HaiErrorDef;
+    readonly ALREADY_RUNNING: _h_ai_core.HaiErrorDef;
+    readonly NOT_RUNNING: _h_ai_core.HaiErrorDef;
+    readonly LOCK_ACQUIRE_FAILED: _h_ai_core.HaiErrorDef;
+    readonly JS_COMPILE_FAILED: _h_ai_core.HaiErrorDef;
+    readonly HOOK_EXECUTION_FAILED: _h_ai_core.HaiErrorDef;
+};
+/** 任务参数字典（键值对） */
+type TaskParams = Record<string, unknown>;
+/** 任务触发类型 */
+type TaskTriggerType = 'scheduled' | 'manual';
+/** 任务处理器类型 */
+type TaskHandlerKind = 'api' | 'js';
+/** 失败重试策略 */
+interface TaskRetryPolicy {
+    /** 最大尝试次数（包含首次执行，最小 1） */
+    maxAttempts: number;
+    /** 每次重试前的退避时间（毫秒）；按顺序对应第 2、3... 次尝试 */
+    backoffMs?: number[];
+}
+/** 任务执行目标类型 */
+type TaskExecutionTargetType = TaskHandlerKind | 'hook';
+/**
+ * API 任务配置
+ */
+interface ApiTaskConfig {
+    /** 处理器类型 */
+    kind: 'api';
+    /** 请求 URL */
+    url: string;
+    /** HTTP 方法（默认 GET） */
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    /** 请求头 */
+    headers?: Record<string, string>;
+    /** 请求体（POST/PUT/PATCH 时使用） */
+    body?: unknown;
+    /** 超时时间，单位毫秒（默认 30000） */
+    timeout?: number;
+}
+/**
+ * JS 任务配置
+ *
+ * `code` 为 JS 函数字符串，例如：
+ * `(context) => ({ taskId: context.task.id, params: context.params })`
+ */
+interface JsTaskConfig {
+    /** 处理器类型 */
+    kind: 'js';
+    /** JS 函数字符串 */
+    code: string;
+    /** 软超时时间，单位毫秒 */
+    timeout?: number;
+}
+/** 统一任务处理器配置 */
+type TaskHandlerConfig = ApiTaskConfig | JsTaskConfig;
+/**
+ * 任务定义
+ *
+ * @example
+ * ```ts
+ * const jsTask: TaskDefinition = {
+ *   id: 'cleanup',
+ *   name: '清理过期数据',
+ *   cron: '0 2 * * *',
+ *   params: { channel: 'nightly' },
+ *   handler: {
+ *     kind: 'js',
+ *     code: '(context) => ({ taskId: context.task.id, params: context.params })',
+ *   },
+ * }
+ *
+ * const apiTask: TaskDefinition = {
+ *   id: 'health-check',
+ *   name: '健康检查',
+ *   cron: '&#42;/5 * * * *',
+ *   handler: {
+ *     kind: 'api',
+ *     url: 'https://api.example.com/health',
+ *     method: 'GET',
+ *   },
+ * }
+ * ```
+ */
+interface TaskDefinition {
+    /** 任务唯一标识 */
+    id: string;
+    /** 任务名称 */
+    name: string;
+    /** 任务描述 */
+    description?: string;
+    /** cron 表达式（标准 5 字段：分 时 日 月 周） */
+    cron: string;
+    /** 是否启用（默认 true） */
+    enabled?: boolean;
+    /** 是否在执行后自动删除（默认 false） */
+    deleteAfterRun?: boolean;
+    /** 失败重试策略 */
+    retry?: TaskRetryPolicy;
+    /** 通用参数 */
+    params?: TaskParams;
+    /** 任务处理器；为空时可由全局事件回调统一处理 */
+    handler?: TaskHandlerConfig;
+}
+/**
+ * 任务触发信息
+ */
+interface TaskTriggerInfo {
+    /** 触发类型 */
+    type: TaskTriggerType;
+    /** 触发来源；定时触发时通常为 null，手工触发时可指定渠道 */
+    source: string | null;
+}
+/**
+ * 任务执行上下文
+ */
+interface SchedulerTaskContext {
+    /** 当前任务 */
+    task: TaskDefinition;
+    /** 任务 ID */
+    taskId: string;
+    /** 当前参数快照 */
+    params: TaskParams;
+    /** 触发信息 */
+    trigger: TaskTriggerInfo;
+}
+/** 编译后的 JS 任务函数 */
+type JsTaskHandler = (context: SchedulerTaskContext) => unknown | Promise<unknown>;
+/** 任务开始事件 */
+interface SchedulerTaskStartEvent {
+    /** 当前任务 */
+    task: TaskDefinition;
+    /** 触发信息 */
+    trigger: TaskTriggerInfo;
+    /** 开始时间（Unix 时间戳，毫秒） */
+    startedAt: number;
+}
+/** 任务执行事件 */
+interface SchedulerTaskExecuteEvent extends SchedulerTaskStartEvent {
+    /** 执行上下文 */
+    context: SchedulerTaskContext;
+}
+/** 任务中断事件 */
+interface SchedulerTaskInterruptedEvent extends SchedulerTaskStartEvent {
+    /** 中断时间（Unix 时间戳，毫秒） */
+    interruptedAt: number;
+    /** 中断原因 */
+    reason: string;
+}
+/** 任务结束事件 */
+interface SchedulerTaskFinishEvent extends SchedulerTaskStartEvent {
+    /** 结束时间（Unix 时间戳，毫秒） */
+    finishedAt: number;
+    /** 执行日志 */
+    log: TaskExecutionLog;
+}
+/**
+ * 全局任务生命周期回调
+ *
+ * - `onTaskExecute` 可用于统一处理无内置 handler 的任务
+ * - `onTaskStart` / `onTaskInterrupted` / `onTaskFinish` 用于观测生命周期
+ */
+interface SchedulerTaskHooks {
+    /** 任务开始前触发 */
+    onTaskStart?: (event: SchedulerTaskStartEvent) => void | Promise<void>;
+    /** 当任务无内置 handler 时，可在此统一执行 */
+    onTaskExecute?: (event: SchedulerTaskExecuteEvent) => unknown | Promise<unknown>;
+    /** 任务被中断时触发 */
+    onTaskInterrupted?: (event: SchedulerTaskInterruptedEvent) => void | Promise<void>;
+    /** 任务结束时触发 */
+    onTaskFinish?: (event: SchedulerTaskFinishEvent) => void | Promise<void>;
+}
+/** 执行状态 */
+type ExecutionStatus = 'success' | 'failed' | 'interrupted';
+/**
+ * 任务执行日志
+ */
+interface TaskExecutionLog {
+    /** 日志 ID */
+    id: number;
+    /** 任务 ID */
+    taskId: string;
+    /** 任务名称 */
+    taskName: string;
+    /** 执行目标类型 */
+    taskType: TaskExecutionTargetType;
+    /** 触发类型 */
+    triggerType: TaskTriggerType;
+    /** 触发来源 */
+    triggerSource: string | null;
+    /** 执行状态 */
+    status: ExecutionStatus;
+    /** 执行结果（JSON 字符串） */
+    result: string | null;
+    /** 错误或中断信息 */
+    error: string | null;
+    /** 开始时间（Unix 时间戳，毫秒） */
+    startedAt: number;
+    /** 结束时间（Unix 时间戳，毫秒） */
+    finishedAt: number;
+    /** 执行耗时（毫秒） */
+    duration: number;
+}
+/**
+ * 执行日志查询选项
+ */
+interface LogQueryOptions {
+    /** 按任务 ID 过滤 */
+    taskId?: string;
+    /** 按状态过滤 */
+    status?: ExecutionStatus;
+    /** 按触发类型过滤 */
+    triggerType?: TaskTriggerType;
+    /** 按触发来源过滤 */
+    triggerSource?: string;
+    /** 仅查询开始时间 >= startedAfter 的日志（Unix 时间戳毫秒） */
+    startedAfter?: number;
+    /** 仅查询开始时间 <= startedBefore 的日志（Unix 时间戳毫秒） */
+    startedBefore?: number;
+    /** 分页参数（page 从 1 开始，pageSize 默认 20） */
+    pagination?: PaginationOptionsInput;
+}
+/** 日志清理策略 */
+interface SchedulerLogCleanupPolicy {
+    /** 最多保留日志条数 */
+    maxLogs?: number;
+    /** 最多保留天数 */
+    retentionDays?: number;
+}
+/**
+ * 任务更新输入
+ *
+ * 可更新的字段包括：名称、cron 表达式、启用状态、参数、处理器。
+ * 任务 ID 不可更新。
+ */
+interface TaskUpdateInput {
+    /** 任务名称 */
+    name?: string;
+    /** 任务描述 */
+    description?: string;
+    /** cron 表达式 */
+    cron?: string;
+    /** 是否启用 */
+    enabled?: boolean;
+    /** 是否在执行后自动删除 */
+    deleteAfterRun?: boolean;
+    /** 失败重试策略；传 null 表示清空重试策略 */
+    retry?: TaskRetryPolicy | null;
+    /** 通用参数 */
+    params?: TaskParams;
+    /** 任务处理器；传 null 表示清空内置处理器 */
+    handler?: TaskHandlerConfig | null;
+}
+/** 手工触发输入 */
+interface TriggerTaskInput {
+    /** 手工触发来源（例如 admin-console / api / cli） */
+    source?: string;
+}
+/**
+ * 调度器初始化输入
+ *
+ * 包含调度器配置、可选的预定义任务列表，以及可选的全局生命周期回调。
+ */
+interface SchedulerInitInput extends SchedulerConfigInput {
+    /** 预定义任务列表（从配置中加载，初始化时自动注册） */
+    tasks?: TaskDefinition[];
+    /** 全局任务生命周期回调 */
+    hooks?: SchedulerTaskHooks;
+}
+/**
+ * 调度器函数接口
+ */
+interface SchedulerFunctions {
+    /** 初始化调度器 */
+    init: (config?: SchedulerInitInput) => Promise<HaiResult<void>>;
+    /** 注册任务 */
+    register: (task: TaskDefinition) => Promise<HaiResult<void>>;
+    /** 注销任务 */
+    unregister: (taskId: string) => Promise<HaiResult<void>>;
+    /** 更新任务 */
+    updateTask: (taskId: string, updates: TaskUpdateInput) => Promise<HaiResult<void>>;
+    /** 启动调度 */
+    start: () => HaiResult<void>;
+    /** 停止调度 */
+    stop: () => HaiResult<void>;
+    /** 手动触发任务 */
+    trigger: (taskId: string, options?: TriggerTaskInput) => Promise<HaiResult<TaskExecutionLog>>;
+    /** 查询执行日志 */
+    getLogs: (options?: LogQueryOptions) => Promise<HaiResult<PaginatedResult<TaskExecutionLog>>>;
+    /** 设置全局任务生命周期回调 */
+    setHooks: (hooks: SchedulerTaskHooks) => HaiResult<void>;
+    /** 清空全局任务生命周期回调 */
+    clearHooks: () => HaiResult<void>;
+    /** 获取已注册任务列表 */
+    readonly tasks: ReadonlyMap<string, TaskDefinition>;
+    /** 当前配置 */
+    readonly config: SchedulerConfig | null;
+    /** 当前生命周期回调 */
+    readonly hooks: Readonly<SchedulerTaskHooks>;
+    /** 是否已初始化 */
+    readonly isInitialized: boolean;
+    /** 调度器是否正在运行 */
+    readonly isRunning: boolean;
+    /** 关闭调度器 */
+    close: () => Promise<void>;
+}
+
+/**
+ * @h-ai/scheduler — 定时任务服务主入口
+ *
+ * 本文件仅负责生命周期管理（init / close）与 API 编排；
+ * 具体业务逻辑委托给 scheduler-functions.ts / scheduler-runner.ts。
+ * @module scheduler-main
+ */
+
+declare const scheduler: SchedulerFunctions;
+
+export { type ApiTaskConfig, type ExecutionStatus, HaiSchedulerError, type JsTaskConfig, type JsTaskHandler, type LogQueryOptions, type SchedulerConfig, type SchedulerConfigInput, SchedulerConfigSchema, type SchedulerFunctions, type SchedulerInitInput, type SchedulerLogCleanupPolicy, type SchedulerTaskContext, type SchedulerTaskExecuteEvent, type SchedulerTaskFinishEvent, type SchedulerTaskHooks, type SchedulerTaskInterruptedEvent, type SchedulerTaskStartEvent, type TaskDefinition, type TaskExecutionLog, type TaskExecutionTargetType, type TaskHandlerConfig, type TaskHandlerKind, type TaskParams, type TaskRetryPolicy, type TaskTriggerInfo, type TaskTriggerType, type TaskUpdateInput, type TriggerTaskInput, scheduler };