@cinnabun/scheduler 0.0.1

package/dist/decorators/scheduled.d.ts

@@ -0,0 +1,5 @@
+import type { ScheduledOptions } from "../interfaces/scheduler-options.js";
+export declare function Scheduled(expressionOrOptions: string | (ScheduledOptions & {
+    fixedRate?: number;
+    fixedDelay?: number;
+}), options?: ScheduledOptions): MethodDecorator;

package/dist/decorators/scheduled.js

@@ -0,0 +1,28 @@
+import { schedulerMetadataStorage } from "../metadata/scheduler-storage.js";
+function addScheduledMetadata(target, propertyKey, config) {
+    schedulerMetadataStorage.add(target.constructor, String(propertyKey), config);
+}
+export function Scheduled(expressionOrOptions, options) {
+    return (target, propertyKey, _descriptor) => {
+        if (typeof expressionOrOptions === "string") {
+            addScheduledMetadata(target, propertyKey, {
+                expression: expressionOrOptions,
+                options: options ? { name: options.name, timezone: options.timezone, enabled: options.enabled } : undefined,
+            });
+        }
+        else {
+            const opts = expressionOrOptions;
+            addScheduledMetadata(target, propertyKey, {
+                expression: undefined,
+                fixedRate: opts.fixedRate,
+                fixedDelay: opts.fixedDelay,
+                initialDelay: opts.initialDelay,
+                options: {
+                    name: opts.name,
+                    timezone: opts.timezone,
+                    enabled: opts.enabled,
+                },
+            });
+        }
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { ScheduledTask } from "./interfaces/scheduled-task.js";
+export type { SchedulerModuleOptions, ScheduledOptions, } from "./interfaces/scheduler-options.js";
+export { SchedulerService } from "./services/scheduler.service.js";
+export { Scheduled } from "./decorators/scheduled.js";
+export { SchedulerModule } from "./scheduler.module.js";
+export { SchedulerPlugin } from "./scheduler.plugin.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { SchedulerService } from "./services/scheduler.service.js";
+export { Scheduled } from "./decorators/scheduled.js";
+export { SchedulerModule } from "./scheduler.module.js";
+export { SchedulerPlugin } from "./scheduler.plugin.js";

package/dist/interfaces/scheduled-task.d.ts

@@ -0,0 +1,14 @@
+export interface ScheduledTask {
+    name: string;
+    expression?: string;
+    handler: () => void | Promise<void>;
+    timezone?: string;
+    enabled: boolean;
+    lastRun?: Date;
+    nextRun?: Date;
+    /** For fixedRate/fixedDelay: interval in ms */
+    fixedRate?: number;
+    fixedDelay?: number;
+    /** Delay before first execution in ms */
+    initialDelay?: number;
+}

package/dist/interfaces/scheduled-task.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/scheduler-options.d.ts

@@ -0,0 +1,15 @@
+export interface SchedulerModuleOptions {
+    timezone?: string;
+    enabled?: boolean;
+}
+export interface ScheduledOptions {
+    name?: string;
+    timezone?: string;
+    enabled?: boolean;
+    /** Spring-style: interval from start of each run (ms) */
+    fixedRate?: number;
+    /** Spring-style: interval from completion of previous run (ms) */
+    fixedDelay?: number;
+    /** Spring-style: delay before first execution (ms) */
+    initialDelay?: number;
+}

package/dist/interfaces/scheduler-options.js

@@ -0,0 +1 @@
+export {};

package/dist/metadata/scheduler-storage.d.ts

@@ -0,0 +1,31 @@
+export interface ScheduledMetadata {
+    target: Function;
+    methodKey: string;
+    expression?: string;
+    fixedRate?: number;
+    fixedDelay?: number;
+    initialDelay?: number;
+    options?: {
+        name?: string;
+        timezone?: string;
+        enabled?: boolean;
+    };
+}
+declare class SchedulerMetadataStorage {
+    private tasks;
+    add(target: Function, methodKey: string, config: {
+        expression?: string;
+        fixedRate?: number;
+        fixedDelay?: number;
+        initialDelay?: number;
+        options?: {
+            name?: string;
+            timezone?: string;
+            enabled?: boolean;
+        };
+    }): void;
+    getAll(): ScheduledMetadata[];
+    reset(): void;
+}
+export declare const schedulerMetadataStorage: SchedulerMetadataStorage;
+export {};

package/dist/metadata/scheduler-storage.js

@@ -0,0 +1,21 @@
+class SchedulerMetadataStorage {
+    tasks = [];
+    add(target, methodKey, config) {
+        this.tasks.push({
+            target,
+            methodKey,
+            expression: config.expression,
+            fixedRate: config.fixedRate,
+            fixedDelay: config.fixedDelay,
+            initialDelay: config.initialDelay,
+            options: config.options,
+        });
+    }
+    getAll() {
+        return [...this.tasks];
+    }
+    reset() {
+        this.tasks = [];
+    }
+}
+export const schedulerMetadataStorage = new SchedulerMetadataStorage();

package/dist/scheduler.module.d.ts

@@ -0,0 +1,5 @@
+import type { SchedulerModuleOptions } from "./interfaces/scheduler-options.js";
+export declare class SchedulerModule {
+    static forRoot(options?: SchedulerModuleOptions): Function;
+    static getOptions(): SchedulerModuleOptions;
+}

package/dist/scheduler.module.js

@@ -0,0 +1,33 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Module } from "@cinnabun/core";
+let moduleOptions = null;
+export class SchedulerModule {
+    static forRoot(options = {}) {
+        moduleOptions = options;
+        let SchedulerDynamicModule = class SchedulerDynamicModule {
+        };
+        SchedulerDynamicModule = __decorate([
+            Module({
+                imports: [],
+                controllers: [],
+                providers: [],
+                exports: [],
+            })
+        ], SchedulerDynamicModule);
+        return SchedulerDynamicModule;
+    }
+    static getOptions() {
+        if (!moduleOptions) {
+            return { timezone: "UTC", enabled: true };
+        }
+        return {
+            timezone: moduleOptions.timezone ?? "UTC",
+            enabled: moduleOptions.enabled ?? true,
+        };
+    }
+}

package/dist/scheduler.plugin.d.ts

@@ -0,0 +1,8 @@
+import type { CinnabunPlugin, PluginContext } from "@cinnabun/core";
+export declare class SchedulerPlugin implements CinnabunPlugin {
+    name: string;
+    private schedulerService;
+    onInit(context: PluginContext): Promise<void>;
+    onReady(_context: PluginContext): Promise<void>;
+    onShutdown(_context: PluginContext): Promise<void>;
+}

package/dist/scheduler.plugin.js

@@ -0,0 +1,26 @@
+import { Logger } from "@cinnabun/core";
+import { SchedulerModule } from "./scheduler.module.js";
+import { SchedulerService } from "./services/scheduler.service.js";
+export class SchedulerPlugin {
+    name = "SchedulerPlugin";
+    schedulerService = null;
+    async onInit(context) {
+        const logger = new Logger("SchedulerPlugin");
+        const options = SchedulerModule.getOptions();
+        const schedulerService = new SchedulerService(context.container);
+        context.container.registerInstance(SchedulerService, schedulerService);
+        this.schedulerService = schedulerService;
+        logger.info(`Scheduler module initialized (timezone: ${options.timezone}, enabled: ${options.enabled})`);
+    }
+    async onReady(_context) {
+        if (this.schedulerService) {
+            this.schedulerService.start();
+        }
+    }
+    async onShutdown(_context) {
+        if (this.schedulerService) {
+            this.schedulerService.stop();
+            this.schedulerService = null;
+        }
+    }
+}

package/dist/services/scheduler.service.d.ts

@@ -0,0 +1,13 @@
+import type { Container } from "@cinnabun/core";
+import type { ScheduledTask } from "../interfaces/scheduled-task.js";
+export declare class SchedulerService {
+    private readonly tasks;
+    private readonly container;
+    private started;
+    constructor(container: Container);
+    schedule(task: ScheduledTask): void;
+    unschedule(name: string): void;
+    getTasks(): ScheduledTask[];
+    start(): void;
+    stop(): void;
+}

package/dist/services/scheduler.service.js

@@ -0,0 +1,157 @@
+import { schedulerMetadataStorage } from "../metadata/scheduler-storage.js";
+import { expandCronExpression } from "../utils/cron-expand.js";
+import { SchedulerModule } from "../scheduler.module.js";
+export class SchedulerService {
+    tasks = new Map();
+    container;
+    started = false;
+    constructor(container) {
+        this.container = container;
+    }
+    schedule(task) {
+        if (!task.enabled)
+            return;
+        const existing = this.tasks.get(task.name);
+        if (existing?.cronRef) {
+            existing.cronRef.stop();
+        }
+        if (existing?.intervalRef) {
+            clearInterval(existing.intervalRef);
+        }
+        if (existing?.timeoutRef) {
+            clearTimeout(existing.timeoutRef);
+        }
+        const taskWithRef = { ...task };
+        this.tasks.set(task.name, taskWithRef);
+        const runHandler = async () => {
+            try {
+                await task.handler();
+                taskWithRef.lastRun = new Date();
+            }
+            catch (err) {
+                console.error(`[Scheduler] Task "${task.name}" failed:`, err);
+            }
+        };
+        if (task.fixedRate !== undefined) {
+            const run = () => {
+                runHandler();
+            };
+            const delay = task.initialDelay ?? 0;
+            const schedule = () => {
+                taskWithRef.intervalRef = setInterval(run, task.fixedRate);
+            };
+            if (delay > 0) {
+                setTimeout(schedule, delay);
+            }
+            else {
+                schedule();
+            }
+            return;
+        }
+        if (task.fixedDelay !== undefined) {
+            const run = async () => {
+                await runHandler();
+                taskWithRef.timeoutRef = setTimeout(run, task.fixedDelay);
+            };
+            const delay = task.initialDelay ?? 0;
+            if (delay > 0) {
+                taskWithRef.timeoutRef = setTimeout(run, delay);
+            }
+            else {
+                run();
+            }
+            return;
+        }
+        if (task.expression) {
+            const expansion = expandCronExpression(task.expression);
+            if (expansion.type === "interval") {
+                const run = () => runHandler();
+                const delay = task.initialDelay ?? 0;
+                const schedule = () => {
+                    taskWithRef.intervalRef = setInterval(run, expansion.intervalMs);
+                };
+                if (delay > 0) {
+                    setTimeout(schedule, delay);
+                }
+                else {
+                    schedule();
+                }
+                return;
+            }
+            try {
+                const cron = require("node-cron");
+                const timezone = task.timezone ?? SchedulerModule.getOptions().timezone;
+                taskWithRef.cronRef = cron.schedule(expansion.expression, () => runHandler(), timezone ? { timezone } : undefined);
+            }
+            catch (err) {
+                console.error(`[Scheduler] Failed to schedule cron "${task.expression}" for "${task.name}":`, err);
+            }
+        }
+    }
+    unschedule(name) {
+        const task = this.tasks.get(name);
+        if (!task)
+            return;
+        if (task.cronRef) {
+            task.cronRef.stop();
+            task.cronRef = undefined;
+        }
+        if (task.intervalRef) {
+            clearInterval(task.intervalRef);
+            task.intervalRef = undefined;
+        }
+        if (task.timeoutRef) {
+            clearTimeout(task.timeoutRef);
+            task.timeoutRef = undefined;
+        }
+        this.tasks.delete(name);
+    }
+    getTasks() {
+        return Array.from(this.tasks.values()).map(({ cronRef, intervalRef, timeoutRef, ...t }) => t);
+    }
+    start() {
+        if (this.started)
+            return;
+        const options = SchedulerModule.getOptions();
+        if (options.enabled === false)
+            return;
+        const allMeta = schedulerMetadataStorage.getAll();
+        const timezone = options.timezone ?? "UTC";
+        for (const meta of allMeta) {
+            let instance;
+            try {
+                instance = this.container.resolve(meta.target);
+            }
+            catch {
+                continue;
+            }
+            const method = instance[meta.methodKey];
+            if (typeof method !== "function")
+                continue;
+            const enabled = meta.options?.enabled ?? true;
+            const taskName = meta.options?.name ?? `${meta.target.name}.${meta.methodKey}`;
+            const taskTimezone = meta.options?.timezone ?? timezone;
+            const handler = () => method.call(instance);
+            const task = {
+                name: taskName,
+                enabled,
+                handler,
+                timezone: taskTimezone,
+                expression: meta.expression,
+                fixedRate: meta.fixedRate,
+                fixedDelay: meta.fixedDelay,
+                initialDelay: meta.initialDelay,
+            };
+            this.schedule(task);
+        }
+        this.started = true;
+    }
+    stop() {
+        if (!this.started)
+            return;
+        for (const [name] of this.tasks) {
+            this.unschedule(name);
+        }
+        this.started = false;
+    }
+}

package/dist/utils/cron-expand.d.ts

@@ -0,0 +1,8 @@
+export type CronExpansionResult = {
+    type: "cron";
+    expression: string;
+} | {
+    type: "interval";
+    intervalMs: number;
+};
+export declare function expandCronExpression(input: string): CronExpansionResult;

package/dist/utils/cron-expand.js

@@ -0,0 +1,38 @@
+const SHORTCUTS = {
+    "@yearly": "0 0 1 1 *",
+    "@annually": "0 0 1 1 *",
+    "@monthly": "0 0 1 * *",
+    "@weekly": "0 0 * * 0",
+    "@daily": "0 0 * * *",
+    "@midnight": "0 0 * * *",
+    "@hourly": "0 * * * *",
+};
+const EVERY_REGEX = /^@every\s+(\d+)(s|m|h|d)$/i;
+export function expandCronExpression(input) {
+    const trimmed = input.trim();
+    const shortcut = SHORTCUTS[trimmed];
+    if (shortcut) {
+        return { type: "cron", expression: shortcut };
+    }
+    const everyMatch = trimmed.match(EVERY_REGEX);
+    if (everyMatch) {
+        const value = parseInt(everyMatch[1], 10);
+        const unit = everyMatch[2].toLowerCase();
+        if (value <= 0) {
+            throw new Error(`Invalid @every value: ${value}`);
+        }
+        switch (unit) {
+            case "s":
+                return { type: "interval", intervalMs: value * 1000 };
+            case "m":
+                return { type: "cron", expression: `*/${value} * * * *` };
+            case "h":
+                return { type: "cron", expression: `0 */${value} * * *` };
+            case "d":
+                return { type: "cron", expression: `0 0 */${value} * *` };
+            default:
+                throw new Error(`Unknown @every unit: ${unit}`);
+        }
+    }
+    return { type: "cron", expression: trimmed };
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@cinnabun/scheduler",
+  "version": "0.0.1",
+  "description": "Task scheduler for Cinnabun with cron and Spring-style fixedRate/fixedDelay",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist"],
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "scripts": {
+    "test": "bun test",
+    "build": "tsc",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": ["cinnabun", "scheduler", "cron", "scheduled"],
+  "peerDependencies": {
+    "@cinnabun/core": "^0.0.3",
+    "node-cron": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "node-cron": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@cinnabun/core": "workspace:*",
+    "@types/bun": "latest",
+    "node-cron": "^3.0.3",
+    "reflect-metadata": "^0.2.2",
+    "typescript": "^5.9.3"
+  }
+}