@zhin.js/schedule-feature 1.1.3 → 1.1.5

package/README.md

@@ -4,14 +4,19 @@ Plugin Runtime 的 generation-owned Schedule Feature。插件在 `schedules/<nam
 
 ```ts
 import { defineSchedule } from '@zhin.js/schedule-feature';
+import { reportServiceToken } from './report-service.js';
 
 export default defineSchedule({
   cron: '0 0 9 * * *',
   description: 'Daily report',
-  async execute() {
-    // work
+  async execute(ctx) {
+    await ctx.use(reportServiceToken).sendDailyReport();
   },
 });
 ```
 
 也可在 `plugin.ts` 的 `setup({ addSchedule })` 中注入同一定义。Feature 在新 generation 激活时通过 owner-scoped `scheduleHostToken` 注册任务，并在旧 generation lease 释放后撤销旧注册。
+
+`execute(ctx)` 的 `owner`、`generation`、`config`、`use(token)` 与 `project(feature)` 来自本次任务所属的 generation。目录声明和 `addSchedule` 使用同一接口；旧代停止接纳新执行，已进入的任务通过现有操作 lease 完成。无入站消息的后台任务不提供 Message、sender 或交互。
+
+可以用 `defineSchedule<MyConfig>(definition)` 标注插件配置。跨重启的提醒、取消状态和投递目标应存入 owner 的 PersistentState；不要把 `ctx`、snapshot、Message、Client 或回调写入 cache 文件。cron、重叠、错过执行和投递未知的处理是不同问题，插件应明确业务策略，不能把再次执行等同于安全重试。

package/lib/definition.d.ts

@@ -1,9 +1,15 @@
-import type { ScheduleJobRegistration } from '@zhin.js/plugin-runtime';
-export type ScheduleDefinition = Omit<ScheduleJobRegistration, 'id' | 'owner'>;
+import type { CapabilityContext } from '@zhin.js/feature-kit';
+/** Operation-scoped owner, configuration and resources; never persist this context. */
+export type ScheduleContext<TConfig = unknown> = CapabilityContext<TConfig>;
+export interface ScheduleDefinition<TConfig = unknown> {
+    readonly cron: string;
+    readonly description?: string;
+    execute(context: ScheduleContext<TConfig>): void | Promise<void>;
+}
 declare module '@zhin.js/plugin-runtime' {
-    interface PluginSetupContext {
-        addSchedule(localName: string, definition: ScheduleDefinition): void;
+    interface PluginSetupContext<TConfig = unknown> {
+        addSchedule(localName: string, definition: ScheduleDefinition<TConfig>): void;
     }
 }
-export declare function defineSchedule(definition: ScheduleDefinition): Readonly<ScheduleDefinition>;
-export declare function parseScheduleDefinition(value: unknown): Readonly<ScheduleDefinition>;
+export declare function defineSchedule<TConfig = unknown>(definition: ScheduleDefinition<TConfig>): Readonly<ScheduleDefinition<TConfig>>;
+export declare function parseScheduleDefinition<TConfig = unknown>(value: unknown): Readonly<ScheduleDefinition<TConfig>>;

package/lib/index.d.ts

@@ -1,4 +1,4 @@
 export { defineSchedule, parseScheduleDefinition } from './definition.js';
-export type { ScheduleDefinition } from './definition.js';
+export type { ScheduleDefinition, ScheduleContext } from './definition.js';
 export { ScheduleIndex } from './schedule-index.js';
 export { default, scheduleFeatureId } from './provider.js';

package/lib/provider.d.ts

@@ -1,4 +1,4 @@
 import { ScheduleIndex } from './schedule-index.js';
 export declare const scheduleFeatureId: import("@zhin.js/plugin-runtime").FeatureId;
-declare const scheduleFeature: Readonly<import("@zhin.js/feature-kit").FeatureProvider<Readonly<import("./definition.js").ScheduleDefinition>, ScheduleIndex>>;
+declare const scheduleFeature: Readonly<import("@zhin.js/feature-kit").FeatureProvider<Readonly<import("./definition.js").ScheduleDefinition<unknown>>, ScheduleIndex>>;
 export default scheduleFeature;

package/lib/provider.js

@@ -12,7 +12,7 @@ const scheduleFeature = defineFeatureProvider({
                 id: 'schedules-index',
                 layouts: [{ segments: ['schedules', capture('name')], localName: (values) => captured(values, 'name') }],
             })],
-        validate: parseScheduleDefinition,
+        validate: value => parseScheduleDefinition(value),
     },
     runtime: {
         project(slots, context) {

package/lib/schedule-index.d.ts

@@ -1,4 +1,4 @@
-import { type CapabilitySlot, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import { generationAdmissionSource, type CapabilitySlot, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
 import type { ScheduleDefinition } from './definition.js';
 export declare class ScheduleIndex {
     #private;
@@ -8,4 +8,6 @@ export declare class ScheduleIndex {
     constructor(slots: readonly Readonly<CapabilitySlot<ScheduleDefinition>>[], snapshot: RuntimeSnapshot);
     start(): void;
     stop(): void;
+    /** @internal Candidate callbacks only enter after their projection is published. */
+    get [generationAdmissionSource](): import("@zhin.js/plugin-runtime").GenerationAdmissionGate[];
 }

package/lib/schedule-index.js

@@ -1,9 +1,12 @@
-import { scheduleHostToken, } from '@zhin.js/plugin-runtime';
+import { scheduleHostToken, stagePluginScheduleRegistration, createGenerationAdmissionGate, createPluginScheduleCandidate, generationAdmissionSource, scopeSetupFinalizer, } from '@zhin.js/plugin-runtime';
+import { createCapabilityContext } from '@zhin.js/feature-kit';
 export class ScheduleIndex {
     slots;
     snapshot;
     $projection = 'zhin.schedule-index/1';
     #disposers = [];
+    #admission = createGenerationAdmissionGate();
+    #hosts = new Map();
     #started = false;
     constructor(slots, snapshot) {
         this.slots = slots;
@@ -19,22 +22,49 @@ export class ScheduleIndex {
                 const host = resources?.get(scheduleHostToken.id);
                 if (!host)
                     throw new Error(`Schedule Host is unavailable for ${slot.owner}`);
-                this.#disposers.push(host.register({
+                let candidate = this.#hosts.get(slot.owner);
+                if (!candidate) {
+                    candidate = createPluginScheduleCandidate(host, this.#admission);
+                    this.#hosts.set(slot.owner, candidate);
+                }
+                this.#disposers.push(stagePluginScheduleRegistration(candidate, {
                     id: slot.localName,
                     cron: slot.definition.cron,
                     description: slot.definition.description,
-                    execute: slot.definition.execute,
+                    execute: () => slot.definition.execute(createCapabilityContext(this.snapshot, slot.owner, this.#admission)),
                 }));
             }
         }
         catch (error) {
-            this.stop();
+            const cleanupErrors = [];
+            try {
+                this.stop();
+            }
+            catch (cleanupError) {
+                cleanupErrors.push(cleanupError);
+            }
+            if (cleanupErrors.length > 0)
+                throw new AggregateError([error, ...cleanupErrors], 'Schedule activation and cleanup both failed', { cause: error });
             throw error;
         }
     }
     stop() {
-        for (const dispose of this.#disposers.splice(0).reverse())
-            dispose();
+        const errors = [];
+        for (const dispose of this.#disposers.splice(0).reverse()) {
+            try {
+                dispose();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        for (const host of this.#hosts.values())
+            host[scopeSetupFinalizer]('dispose');
+        this.#hosts.clear();
         this.#started = false;
+        if (errors.length > 0)
+            throw new AggregateError(errors, 'Schedule cleanup failed');
     }
+    /** @internal Candidate callbacks only enter after their projection is published. */
+    get [generationAdmissionSource]() { return [this.#admission]; }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/schedule-feature",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "Generation-owned schedule Feature for Zhin Plugin Runtime",
   "type": "module",
   "main": "./lib/index.js",
@@ -8,7 +8,6 @@
   "exports": {
     ".": {
       "types": "./lib/index.d.ts",
-      "development": "./src/index.ts",
       "import": "./lib/index.js"
     }
   },
@@ -17,8 +16,8 @@
     "src"
   ],
   "dependencies": {
-    "@zhin.js/feature-kit": "1.1.3",
-    "@zhin.js/plugin-runtime": "1.1.12"
+    "@zhin.js/plugin-runtime": "1.1.14",
+    "@zhin.js/feature-kit": "1.1.5"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
@@ -32,7 +31,7 @@
     "featureApi": "1.0.0"
   },
   "engines": {
-    "node": "^20.19.0 || >=22.12.0"
+    "node": ">=22.19.0"
   },
   "license": "MIT",
   "private": false,

package/src/definition.ts

@@ -1,22 +1,29 @@
-import type { ScheduleJobRegistration } from '@zhin.js/plugin-runtime';
+import type { CapabilityContext } from '@zhin.js/feature-kit';
 
-export type ScheduleDefinition = Omit<ScheduleJobRegistration, 'id' | 'owner'>;
+/** Operation-scoped owner, configuration and resources; never persist this context. */
+export type ScheduleContext<TConfig = unknown> = CapabilityContext<TConfig>;
+
+export interface ScheduleDefinition<TConfig = unknown> {
+  readonly cron: string;
+  readonly description?: string;
+  execute(context: ScheduleContext<TConfig>): void | Promise<void>;
+}
 
 declare module '@zhin.js/plugin-runtime' {
-  interface PluginSetupContext {
-    addSchedule(localName: string, definition: ScheduleDefinition): void;
+  interface PluginSetupContext<TConfig = unknown> {
+    addSchedule(localName: string, definition: ScheduleDefinition<TConfig>): void;
   }
 }
 
-export function defineSchedule(definition: ScheduleDefinition): Readonly<ScheduleDefinition> {
-  return parseScheduleDefinition(definition);
+export function defineSchedule<TConfig = unknown>(definition: ScheduleDefinition<TConfig>): Readonly<ScheduleDefinition<TConfig>> {
+  return parseScheduleDefinition<TConfig>(definition);
 }
 
-export function parseScheduleDefinition(value: unknown): Readonly<ScheduleDefinition> {
+export function parseScheduleDefinition<TConfig = unknown>(value: unknown): Readonly<ScheduleDefinition<TConfig>> {
   if (!value || typeof value !== 'object') {
     throw new TypeError('Schedule definition must be an object');
   }
-  const definition = value as Partial<ScheduleDefinition>;
+  const definition = value as Partial<ScheduleDefinition<TConfig>>;
   if (typeof definition.cron !== 'string' || definition.cron.trim() === '') {
     throw new TypeError('Schedule definition requires a non-empty cron string');
   }

package/src/index.ts

@@ -1,4 +1,4 @@
 export { defineSchedule, parseScheduleDefinition } from './definition.js';
-export type { ScheduleDefinition } from './definition.js';
+export type { ScheduleDefinition, ScheduleContext } from './definition.js';
 export { ScheduleIndex } from './schedule-index.js';
 export { default, scheduleFeatureId } from './provider.js';

package/src/provider.ts

@@ -14,7 +14,7 @@ const scheduleFeature = defineFeatureProvider({
       id: 'schedules-index',
       layouts: [{ segments: ['schedules', capture('name')], localName: (values) => captured(values, 'name') }],
     })],
-    validate: parseScheduleDefinition,
+    validate: value => parseScheduleDefinition(value),
   },
   runtime: {
     project(slots, context) {

package/src/schedule-index.ts

@@ -1,15 +1,24 @@
 import {
   scheduleHostToken,
+  stagePluginScheduleRegistration,
+  createGenerationAdmissionGate,
+  createPluginScheduleCandidate,
+  generationAdmissionSource,
+  scopeSetupFinalizer,
   type CapabilitySlot,
   type Dispose,
   type PluginScheduleHost,
   type RuntimeSnapshot,
+  type PluginId,
 } from '@zhin.js/plugin-runtime';
 import type { ScheduleDefinition } from './definition.js';
+import { createCapabilityContext } from '@zhin.js/feature-kit';
 
 export class ScheduleIndex {
   readonly $projection = 'zhin.schedule-index/1' as const;
   readonly #disposers: Dispose[] = [];
+  readonly #admission = createGenerationAdmissionGate();
+  readonly #hosts = new Map<PluginId, PluginScheduleHost>();
   #started = false;
 
   constructor(
@@ -25,21 +34,37 @@ export class ScheduleIndex {
         const resources = this.snapshot.resources.get(slot.owner);
         const host = resources?.get(scheduleHostToken.id) as PluginScheduleHost | undefined;
         if (!host) throw new Error(`Schedule Host is unavailable for ${slot.owner}`);
-        this.#disposers.push(host.register({
+        let candidate = this.#hosts.get(slot.owner);
+        if (!candidate) {
+          candidate = createPluginScheduleCandidate(host, this.#admission);
+          this.#hosts.set(slot.owner, candidate);
+        }
+        this.#disposers.push(stagePluginScheduleRegistration(candidate, {
           id: slot.localName,
           cron: slot.definition.cron,
           description: slot.definition.description,
-          execute: slot.definition.execute,
+          execute: () => slot.definition.execute(createCapabilityContext(this.snapshot, slot.owner, this.#admission)),
         }));
       }
     } catch (error) {
-      this.stop();
+      const cleanupErrors: unknown[] = [];
+      try { this.stop(); } catch (cleanupError) { cleanupErrors.push(cleanupError); }
+      if (cleanupErrors.length > 0) throw new AggregateError([error, ...cleanupErrors], 'Schedule activation and cleanup both failed', { cause: error });
       throw error;
     }
   }
 
   stop(): void {
-    for (const dispose of this.#disposers.splice(0).reverse()) dispose();
+    const errors: unknown[] = [];
+    for (const dispose of this.#disposers.splice(0).reverse()) {
+      try { dispose(); } catch (error) { errors.push(error); }
+    }
+    for (const host of this.#hosts.values()) host[scopeSetupFinalizer]('dispose');
+    this.#hosts.clear();
     this.#started = false;
+    if (errors.length > 0) throw new AggregateError(errors, 'Schedule cleanup failed');
   }
+
+  /** @internal Candidate callbacks only enter after their projection is published. */
+  get [generationAdmissionSource]() { return [this.#admission]; }
 }