@zhin.js/schedule-feature 1.1.0

package/README.md

@@ -0,0 +1,17 @@
+# @zhin.js/schedule-feature
+
+Plugin Runtime 的 generation-owned Schedule Feature。插件在 `schedules/<name>/index.ts` 默认导出 `defineSchedule(...)`；同目录其他文件是 helper，不会被解析成任务。
+
+```ts
+import { defineSchedule } from '@zhin.js/schedule-feature';
+
+export default defineSchedule({
+  cron: '0 0 9 * * *',
+  description: 'Daily report',
+  async execute() {
+    // work
+  },
+});
+```
+
+也可在 `plugin.ts` 的 `setup({ addSchedule })` 中注入同一定义。Feature 在新 generation 激活时通过 owner-scoped `scheduleHostToken` 注册任务，并在旧 generation lease 释放后撤销旧注册。

package/lib/definition.d.ts

@@ -0,0 +1,9 @@
+import type { ScheduleJobRegistration } from '@zhin.js/plugin-runtime';
+export type ScheduleDefinition = Omit<ScheduleJobRegistration, 'id' | 'owner'>;
+declare module '@zhin.js/plugin-runtime' {
+    interface PluginSetupContext {
+        addSchedule(localName: string, definition: ScheduleDefinition): void;
+    }
+}
+export declare function defineSchedule(definition: ScheduleDefinition): Readonly<ScheduleDefinition>;
+export declare function parseScheduleDefinition(value: unknown): Readonly<ScheduleDefinition>;

package/lib/definition.js

@@ -0,0 +1,23 @@
+export function defineSchedule(definition) {
+    return parseScheduleDefinition(definition);
+}
+export function parseScheduleDefinition(value) {
+    if (!value || typeof value !== 'object') {
+        throw new TypeError('Schedule definition must be an object');
+    }
+    const definition = value;
+    if (typeof definition.cron !== 'string' || definition.cron.trim() === '') {
+        throw new TypeError('Schedule definition requires a non-empty cron string');
+    }
+    if (typeof definition.execute !== 'function') {
+        throw new TypeError('Schedule definition requires execute()');
+    }
+    if (definition.description !== undefined && typeof definition.description !== 'string') {
+        throw new TypeError('Schedule definition description must be a string');
+    }
+    return Object.freeze({
+        cron: definition.cron,
+        ...(definition.description === undefined ? {} : { description: definition.description }),
+        execute: definition.execute,
+    });
+}

package/lib/index.d.ts

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

package/lib/index.js

@@ -0,0 +1,3 @@
+export { defineSchedule, parseScheduleDefinition } from './definition.js';
+export { ScheduleIndex } from './schedule-index.js';
+export { default, scheduleFeatureId } from './provider.js';

package/lib/provider.d.ts

@@ -0,0 +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>>;
+export default scheduleFeature;

package/lib/provider.js

@@ -0,0 +1,31 @@
+import { featureId } from '@zhin.js/plugin-runtime';
+import { capture, captured, defineFeatureProvider, directoryModules } from '@zhin.js/feature-kit';
+import { parseScheduleDefinition } from './definition.js';
+import { ScheduleIndex } from './schedule-index.js';
+export const scheduleFeatureId = featureId('zhin.schedule');
+const scheduleFeature = defineFeatureProvider({
+    protocol: 1,
+    id: scheduleFeatureId,
+    authoring: {
+        setupMethod: 'addSchedule',
+        conventions: [directoryModules({
+                id: 'schedules-index',
+                layouts: [{ segments: ['schedules', capture('name')], localName: (values) => captured(values, 'name') }],
+            })],
+        validate: parseScheduleDefinition,
+    },
+    runtime: {
+        project(slots, context) {
+            const index = new ScheduleIndex(slots, context.snapshot);
+            return {
+                value: index,
+                dispose: () => index.stop(),
+                handoff: {
+                    activateNext: () => index.start(),
+                    deactivateNext: () => index.stop(),
+                },
+            };
+        },
+    },
+});
+export default scheduleFeature;

package/lib/schedule-index.d.ts

@@ -0,0 +1,11 @@
+import { type CapabilitySlot, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import type { ScheduleDefinition } from './definition.js';
+export declare class ScheduleIndex {
+    #private;
+    private readonly slots;
+    private readonly snapshot;
+    readonly $projection: "zhin.schedule-index/1";
+    constructor(slots: readonly Readonly<CapabilitySlot<ScheduleDefinition>>[], snapshot: RuntimeSnapshot);
+    start(): void;
+    stop(): void;
+}

package/lib/schedule-index.js

@@ -0,0 +1,40 @@
+import { scheduleHostToken, } from '@zhin.js/plugin-runtime';
+export class ScheduleIndex {
+    slots;
+    snapshot;
+    $projection = 'zhin.schedule-index/1';
+    #disposers = [];
+    #started = false;
+    constructor(slots, snapshot) {
+        this.slots = slots;
+        this.snapshot = snapshot;
+    }
+    start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        try {
+            for (const slot of this.slots) {
+                const resources = this.snapshot.resources.get(slot.owner);
+                const host = resources?.get(scheduleHostToken.id);
+                if (!host)
+                    throw new Error(`Schedule Host is unavailable for ${slot.owner}`);
+                this.#disposers.push(host.register({
+                    id: slot.localName,
+                    cron: slot.definition.cron,
+                    description: slot.definition.description,
+                    execute: slot.definition.execute,
+                }));
+            }
+        }
+        catch (error) {
+            this.stop();
+            throw error;
+        }
+    }
+    stop() {
+        for (const dispose of this.#disposers.splice(0).reverse())
+            dispose();
+        this.#started = false;
+    }
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@zhin.js/schedule-feature",
+  "version": "1.1.0",
+  "description": "Generation-owned schedule Feature for Zhin Plugin Runtime",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "development": "./src/index.ts",
+      "import": "./lib/index.js"
+    }
+  },
+  "files": ["lib", "src"],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf lib",
+    "test": "vitest run --root ../../.. packages/im/schedule-feature/tests"
+  },
+  "dependencies": {
+    "@zhin.js/feature-kit": "workspace:*",
+    "@zhin.js/plugin-runtime": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.2",
+    "typescript": "^6.0.3"
+  },
+  "zhin": {
+    "protocol": 1,
+    "type": "feature",
+    "entry": "./lib/provider.js",
+    "engine": "^1.0.0",
+    "featureApi": "1.0.0"
+  },
+  "engines": { "node": "^20.19.0 || >=22.12.0" },
+  "license": "MIT",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhinjs/zhin.git",
+    "directory": "packages/im/schedule-feature"
+  },
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org" }
+}

package/src/definition.ts

@@ -0,0 +1,34 @@
+import type { ScheduleJobRegistration } from '@zhin.js/plugin-runtime';
+
+export type ScheduleDefinition = Omit<ScheduleJobRegistration, 'id' | 'owner'>;
+
+declare module '@zhin.js/plugin-runtime' {
+  interface PluginSetupContext {
+    addSchedule(localName: string, definition: ScheduleDefinition): void;
+  }
+}
+
+export function defineSchedule(definition: ScheduleDefinition): Readonly<ScheduleDefinition> {
+  return parseScheduleDefinition(definition);
+}
+
+export function parseScheduleDefinition(value: unknown): Readonly<ScheduleDefinition> {
+  if (!value || typeof value !== 'object') {
+    throw new TypeError('Schedule definition must be an object');
+  }
+  const definition = value as Partial<ScheduleDefinition>;
+  if (typeof definition.cron !== 'string' || definition.cron.trim() === '') {
+    throw new TypeError('Schedule definition requires a non-empty cron string');
+  }
+  if (typeof definition.execute !== 'function') {
+    throw new TypeError('Schedule definition requires execute()');
+  }
+  if (definition.description !== undefined && typeof definition.description !== 'string') {
+    throw new TypeError('Schedule definition description must be a string');
+  }
+  return Object.freeze({
+    cron: definition.cron,
+    ...(definition.description === undefined ? {} : { description: definition.description }),
+    execute: definition.execute,
+  });
+}

package/src/index.ts

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

package/src/provider.ts

@@ -0,0 +1,34 @@
+import { featureId } from '@zhin.js/plugin-runtime';
+import { capture, captured, defineFeatureProvider, directoryModules } from '@zhin.js/feature-kit';
+import { parseScheduleDefinition } from './definition.js';
+import { ScheduleIndex } from './schedule-index.js';
+
+export const scheduleFeatureId = featureId('zhin.schedule');
+
+const scheduleFeature = defineFeatureProvider({
+  protocol: 1,
+  id: scheduleFeatureId,
+  authoring: {
+    setupMethod: 'addSchedule',
+    conventions: [directoryModules({
+      id: 'schedules-index',
+      layouts: [{ segments: ['schedules', capture('name')], localName: (values) => captured(values, 'name') }],
+    })],
+    validate: parseScheduleDefinition,
+  },
+  runtime: {
+    project(slots, context) {
+      const index = new ScheduleIndex(slots, context.snapshot);
+      return {
+        value: index,
+        dispose: () => index.stop(),
+        handoff: {
+          activateNext: () => index.start(),
+          deactivateNext: () => index.stop(),
+        },
+      };
+    },
+  },
+});
+
+export default scheduleFeature;

package/src/schedule-index.ts

@@ -0,0 +1,45 @@
+import {
+  scheduleHostToken,
+  type CapabilitySlot,
+  type Dispose,
+  type PluginScheduleHost,
+  type RuntimeSnapshot,
+} from '@zhin.js/plugin-runtime';
+import type { ScheduleDefinition } from './definition.js';
+
+export class ScheduleIndex {
+  readonly $projection = 'zhin.schedule-index/1' as const;
+  readonly #disposers: Dispose[] = [];
+  #started = false;
+
+  constructor(
+    private readonly slots: readonly Readonly<CapabilitySlot<ScheduleDefinition>>[],
+    private readonly snapshot: RuntimeSnapshot,
+  ) {}
+
+  start(): void {
+    if (this.#started) return;
+    this.#started = true;
+    try {
+      for (const slot of this.slots) {
+        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({
+          id: slot.localName,
+          cron: slot.definition.cron,
+          description: slot.definition.description,
+          execute: slot.definition.execute,
+        }));
+      }
+    } catch (error) {
+      this.stop();
+      throw error;
+    }
+  }
+
+  stop(): void {
+    for (const dispose of this.#disposers.splice(0).reverse()) dispose();
+    this.#started = false;
+  }
+}