@forinda/kickjs-cron 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Felix Orinda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,193 @@
+import { AppAdapter, Container } from '@forinda/kickjs-core';
+export { CRON_META, Cron, CronJobMeta, getCronJobs } from '@forinda/kickjs-core';
+
+/**
+ * Abstract scheduler backend. Implement this interface to use any
+ * cron library or timer strategy with the CronAdapter.
+ *
+ * KickJS ships two built-in implementations:
+ * - `CronerScheduler` — production-grade (requires `croner`)
+ * - `IntervalScheduler` — zero-dep fallback (setInterval-based)
+ *
+ * @example
+ * ```ts
+ * // Custom scheduler using node-cron
+ * import cron from 'node-cron'
+ *
+ * class NodeCronScheduler implements CronScheduler {
+ *   private tasks: cron.ScheduledTask[] = []
+ *
+ *   schedule(expression, callback, options) {
+ *     const task = cron.schedule(expression, callback, {
+ *       timezone: options?.timezone,
+ *     })
+ *     this.tasks.push(task)
+ *     return task
+ *   }
+ *
+ *   stop(handle) { handle.stop() }
+ *   stopAll() { this.tasks.forEach(t => t.stop()); this.tasks = [] }
+ * }
+ * ```
+ */
+interface CronScheduler {
+    /** Schedule a callback using a cron expression. Returns an opaque handle. */
+    schedule(expression: string, callback: () => void | Promise<void>, options?: {
+        timezone?: string;
+    }): any;
+    /** Stop a single scheduled job by its handle. */
+    stop(handle: any): void;
+    /** Stop all scheduled jobs. Called on shutdown. */
+    stopAll(): void;
+}
+/**
+ * Production-grade scheduler powered by `croner`.
+ *
+ * Features:
+ * - Full cron syntax: 5, 6, or 7 fields (with seconds and year)
+ * - OCPS 1.4 compliant
+ * - Timezone and DST support
+ * - Advanced patterns: L (last), W (weekday), # (nth occurrence)
+ * - Zero drift — fires at exact cron boundaries
+ *
+ * Requires `croner` as a peer dependency:
+ * ```bash
+ * pnpm add croner
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { CronAdapter, CronerScheduler } from '@forinda/kickjs-cron'
+ *
+ * new CronAdapter({
+ *   services: [ReportService],
+ *   scheduler: new CronerScheduler(),
+ * })
+ * ```
+ */
+declare class CronerScheduler implements CronScheduler {
+    private CronClass;
+    private jobs;
+    /**
+     * @param cronerModule - Optional: pass the croner module directly to avoid
+     *   dynamic import issues in bundlers. e.g. `new CronerScheduler(require('croner'))`
+     */
+    constructor(cronerModule?: {
+        Cron: any;
+    } | any);
+    /** @internal Load croner dynamically if not passed via constructor */
+    init(): Promise<void>;
+    schedule(expression: string, callback: () => void | Promise<void>, options?: {
+        timezone?: string;
+    }): any;
+    stop(handle: any): void;
+    stopAll(): void;
+}
+/**
+ * Lightweight fallback scheduler using `setInterval`.
+ * Converts common cron patterns to millisecond intervals.
+ *
+ * Use for development or simple recurring tasks. For production,
+ * use CronerScheduler or implement a custom CronScheduler.
+ *
+ * Limitations:
+ * - No timezone support
+ * - No day-of-week, day-of-month, or month-specific scheduling
+ * - Complex expressions fall back to 1-hour intervals
+ * - Timer drift over long periods
+ *
+ * @example
+ * ```ts
+ * import { CronAdapter, IntervalScheduler } from '@forinda/kickjs-cron'
+ *
+ * new CronAdapter({
+ *   services: [ReportService],
+ *   scheduler: new IntervalScheduler(),
+ * })
+ * ```
+ */
+declare class IntervalScheduler implements CronScheduler {
+    private timers;
+    schedule(expression: string, callback: () => void | Promise<void>, options?: {
+        timezone?: string;
+    }): NodeJS.Timeout;
+    stop(handle: NodeJS.Timeout): void;
+    stopAll(): void;
+}
+
+interface CronAdapterOptions {
+    /**
+     * Service classes that contain @Cron decorated methods.
+     * Must also be decorated with @Service() for DI resolution.
+     */
+    services: any[];
+    /** Enable/disable all cron jobs (default: true) */
+    enabled?: boolean;
+    /**
+     * Scheduler backend. Defaults to CronerScheduler (production-grade)
+     * with automatic fallback to IntervalScheduler if croner is not installed.
+     *
+     * Built-in:
+     * - `new CronerScheduler()` — full cron syntax, timezones, DST (requires `croner`)
+     * - `new IntervalScheduler()` — zero-dep, setInterval-based (dev/simple tasks)
+     *
+     * Or implement `CronScheduler` for node-cron, node-schedule, cloud schedulers, etc.
+     */
+    scheduler?: CronScheduler;
+}
+/**
+ * Cron adapter — scans services for @Cron decorated methods and
+ * schedules them using a pluggable scheduler backend.
+ *
+ * By default, tries `croner` for production-grade scheduling. Falls back
+ * to `setInterval` if croner is not installed.
+ *
+ * @example
+ * ```ts
+ * import { CronAdapter } from '@forinda/kickjs-cron'
+ *
+ * // Auto-detect best available scheduler
+ * bootstrap({
+ *   adapters: [
+ *     new CronAdapter({ services: [ReportService, CleanupService] }),
+ *   ],
+ * })
+ *
+ * // Explicit production scheduler
+ * import { CronerScheduler } from '@forinda/kickjs-cron'
+ *
+ * bootstrap({
+ *   adapters: [
+ *     new CronAdapter({
+ *       services: [ReportService],
+ *       scheduler: new CronerScheduler(),
+ *     }),
+ *   ],
+ * })
+ *
+ * // Custom scheduler
+ * import { NodeCronScheduler } from './my-scheduler'
+ *
+ * bootstrap({
+ *   adapters: [
+ *     new CronAdapter({
+ *       services: [ReportService],
+ *       scheduler: new NodeCronScheduler(),
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
+declare class CronAdapter implements AppAdapter {
+    private options;
+    name: string;
+    private scheduler;
+    private enabled;
+    constructor(options: CronAdapterOptions);
+    afterStart(_server: any, container: Container): Promise<void>;
+    private resolveScheduler;
+    private runJob;
+    shutdown(): void;
+}
+
+export { CronAdapter, type CronAdapterOptions, type CronScheduler, CronerScheduler, IntervalScheduler };

package/dist/index.js

@@ -0,0 +1,212 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/index.ts
+import "reflect-metadata";
+import { Cron, getCronJobs as getCronJobs2, CRON_META } from "@forinda/kickjs-core";
+
+// src/scheduler.ts
+import { Logger } from "@forinda/kickjs-core";
+var log = Logger.for("CronScheduler");
+var CronerScheduler = class {
+  static {
+    __name(this, "CronerScheduler");
+  }
+  CronClass;
+  jobs = [];
+  /**
+  * @param cronerModule - Optional: pass the croner module directly to avoid
+  *   dynamic import issues in bundlers. e.g. `new CronerScheduler(require('croner'))`
+  */
+  constructor(cronerModule) {
+    if (cronerModule) {
+      this.CronClass = cronerModule.Cron ?? cronerModule;
+    }
+  }
+  /** @internal Load croner dynamically if not passed via constructor */
+  async init() {
+    if (this.CronClass) return;
+    try {
+      const mod = await import("croner");
+      this.CronClass = mod.Cron ?? mod;
+    } catch {
+      throw new Error('CronerScheduler requires the "croner" package. Install it: pnpm add croner');
+    }
+  }
+  schedule(expression, callback, options) {
+    if (!this.CronClass) {
+      throw new Error("CronerScheduler not initialized. Ensure CronAdapter calls init() or pass the croner module to the constructor.");
+    }
+    const job = new this.CronClass(expression, {
+      timezone: options?.timezone,
+      protect: true
+    }, callback);
+    this.jobs.push(job);
+    return job;
+  }
+  stop(handle) {
+    handle?.stop?.();
+    this.jobs = this.jobs.filter((j) => j !== handle);
+  }
+  stopAll() {
+    for (const job of this.jobs) {
+      job?.stop?.();
+    }
+    this.jobs = [];
+  }
+};
+var IntervalScheduler = class {
+  static {
+    __name(this, "IntervalScheduler");
+  }
+  timers = [];
+  schedule(expression, callback, options) {
+    const intervalMs = cronToMs(expression);
+    if (intervalMs === null) {
+      throw new Error(`Invalid cron expression: "${expression}"`);
+    }
+    if (options?.timezone) {
+      log.warn("IntervalScheduler does not support timezones. Install croner and use CronerScheduler for timezone support.");
+    }
+    const timer = setInterval(async () => {
+      try {
+        await callback();
+      } catch {
+      }
+    }, intervalMs);
+    this.timers.push(timer);
+    return timer;
+  }
+  stop(handle) {
+    clearInterval(handle);
+    this.timers = this.timers.filter((t) => t !== handle);
+  }
+  stopAll() {
+    for (const timer of this.timers) {
+      clearInterval(timer);
+    }
+    this.timers = [];
+  }
+};
+function cronToMs(expression) {
+  const parts = expression.trim().split(/\s+/);
+  let minute, hour;
+  if (parts.length === 5) {
+    ;
+    [minute, hour] = parts;
+  } else if (parts.length === 6) {
+    ;
+    [, minute, hour] = parts;
+  } else {
+    return null;
+  }
+  if (parts.length === 6 && parts[0].startsWith("*/")) {
+    const secs = parseInt(parts[0].slice(2), 10);
+    if (!isNaN(secs) && secs > 0) return secs * 1e3;
+  }
+  if (minute.startsWith("*/")) {
+    const mins = parseInt(minute.slice(2), 10);
+    if (!isNaN(mins) && mins > 0) return mins * 60 * 1e3;
+  }
+  if (minute === "0" && hour === "*") return 60 * 60 * 1e3;
+  if (minute === "0" && hour.startsWith("*/")) {
+    const hrs = parseInt(hour.slice(2), 10);
+    if (!isNaN(hrs) && hrs > 0) return hrs * 60 * 60 * 1e3;
+  }
+  if (minute === "*" && hour === "*") return 60 * 1e3;
+  if (/^\d+$/.test(minute) && /^\d+$/.test(hour)) {
+    return 24 * 60 * 60 * 1e3;
+  }
+  log.warn(`Complex cron "${expression}" \u2014 using 1h interval. Install croner and use CronerScheduler for exact scheduling.`);
+  return 60 * 60 * 1e3;
+}
+__name(cronToMs, "cronToMs");
+
+// src/adapter.ts
+import { Logger as Logger2, getCronJobs } from "@forinda/kickjs-core";
+var log2 = Logger2.for("CronAdapter");
+var CronAdapter = class {
+  static {
+    __name(this, "CronAdapter");
+  }
+  options;
+  name = "CronAdapter";
+  scheduler = null;
+  enabled;
+  constructor(options) {
+    this.options = options;
+    this.enabled = options.enabled ?? true;
+  }
+  async afterStart(_server, container) {
+    if (!this.enabled) {
+      log2.info("Cron disabled");
+      return;
+    }
+    this.scheduler = await this.resolveScheduler();
+    let totalJobs = 0;
+    for (const ServiceClass of this.options.services) {
+      const jobs = getCronJobs(ServiceClass);
+      if (jobs.length === 0) continue;
+      const instance = container.resolve(ServiceClass);
+      for (const job of jobs) {
+        const label = job.description ?? `${ServiceClass.name}.${job.handlerName}`;
+        try {
+          if (job.runOnInit) {
+            this.runJob(instance, job, label);
+          }
+          this.scheduler.schedule(job.expression, () => this.runJob(instance, job, label), {
+            timezone: job.timezone
+          });
+          totalJobs++;
+          log2.info(`Scheduled: ${label} (${job.expression}${job.timezone ? ` [${job.timezone}]` : ""})`);
+        } catch (err) {
+          log2.error({
+            err
+          }, `Failed to schedule: ${label}`);
+        }
+      }
+    }
+    if (totalJobs > 0) {
+      const schedulerName = this.scheduler.constructor.name;
+      log2.info(`${totalJobs} cron job(s) active [${schedulerName}]`);
+    }
+  }
+  async resolveScheduler() {
+    if (this.options.scheduler) {
+      return this.options.scheduler;
+    }
+    const croner = new CronerScheduler();
+    try {
+      await croner.init();
+      log2.info("Using CronerScheduler (production)");
+      return croner;
+    } catch {
+      log2.warn("croner not installed \u2014 using IntervalScheduler (limited cron support). For production: pnpm add croner");
+      return new IntervalScheduler();
+    }
+  }
+  async runJob(instance, job, label) {
+    try {
+      await instance[job.handlerName]();
+    } catch (err) {
+      log2.error({
+        err
+      }, `Cron job failed: ${label}`);
+    }
+  }
+  shutdown() {
+    if (this.scheduler) {
+      this.scheduler.stopAll();
+    }
+    log2.info("All cron jobs stopped");
+  }
+};
+export {
+  CRON_META,
+  Cron,
+  CronAdapter,
+  CronerScheduler,
+  IntervalScheduler,
+  getCronJobs2 as getCronJobs
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/scheduler.ts","../src/adapter.ts"],"sourcesContent":["import 'reflect-metadata'\n\n// Re-export the @Cron decorator and metadata from core\nexport { Cron, getCronJobs, type CronJobMeta, CRON_META } from '@forinda/kickjs-core'\n\n// Scheduler interface + built-in implementations\nexport { type CronScheduler, CronerScheduler, IntervalScheduler } from './scheduler'\n\n// CronAdapter\nexport { CronAdapter, type CronAdapterOptions } from './adapter'\n","import { Logger } from '@forinda/kickjs-core'\n\nconst log = Logger.for('CronScheduler')\n\n// ── CronScheduler Interface ─────────────────────────────────────────────\n\n/**\n * Abstract scheduler backend. Implement this interface to use any\n * cron library or timer strategy with the CronAdapter.\n *\n * KickJS ships two built-in implementations:\n * - `CronerScheduler` — production-grade (requires `croner`)\n * - `IntervalScheduler` — zero-dep fallback (setInterval-based)\n *\n * @example\n * ```ts\n * // Custom scheduler using node-cron\n * import cron from 'node-cron'\n *\n * class NodeCronScheduler implements CronScheduler {\n *   private tasks: cron.ScheduledTask[] = []\n *\n *   schedule(expression, callback, options) {\n *     const task = cron.schedule(expression, callback, {\n *       timezone: options?.timezone,\n *     })\n *     this.tasks.push(task)\n *     return task\n *   }\n *\n *   stop(handle) { handle.stop() }\n *   stopAll() { this.tasks.forEach(t => t.stop()); this.tasks = [] }\n * }\n * ```\n */\nexport interface CronScheduler {\n  /** Schedule a callback using a cron expression. Returns an opaque handle. */\n  schedule(\n    expression: string,\n    callback: () => void | Promise<void>,\n    options?: { timezone?: string },\n  ): any\n\n  /** Stop a single scheduled job by its handle. */\n  stop(handle: any): void\n\n  /** Stop all scheduled jobs. Called on shutdown. */\n  stopAll(): void\n}\n\n// ── CronerScheduler (production) ────────────────────────────────────────\n\n/**\n * Production-grade scheduler powered by `croner`.\n *\n * Features:\n * - Full cron syntax: 5, 6, or 7 fields (with seconds and year)\n * - OCPS 1.4 compliant\n * - Timezone and DST support\n * - Advanced patterns: L (last), W (weekday), # (nth occurrence)\n * - Zero drift — fires at exact cron boundaries\n *\n * Requires `croner` as a peer dependency:\n * ```bash\n * pnpm add croner\n * ```\n *\n * @example\n * ```ts\n * import { CronAdapter, CronerScheduler } from '@forinda/kickjs-cron'\n *\n * new CronAdapter({\n *   services: [ReportService],\n *   scheduler: new CronerScheduler(),\n * })\n * ```\n */\nexport class CronerScheduler implements CronScheduler {\n  private CronClass: any\n  private jobs: any[] = []\n\n  /**\n   * @param cronerModule - Optional: pass the croner module directly to avoid\n   *   dynamic import issues in bundlers. e.g. `new CronerScheduler(require('croner'))`\n   */\n  constructor(cronerModule?: { Cron: any } | any) {\n    if (cronerModule) {\n      this.CronClass = cronerModule.Cron ?? cronerModule\n    }\n  }\n\n  /** @internal Load croner dynamically if not passed via constructor */\n  async init(): Promise<void> {\n    if (this.CronClass) return\n    try {\n      const mod: any = await import('croner')\n      this.CronClass = mod.Cron ?? mod\n    } catch {\n      throw new Error('CronerScheduler requires the \"croner\" package. Install it: pnpm add croner')\n    }\n  }\n\n  schedule(\n    expression: string,\n    callback: () => void | Promise<void>,\n    options?: { timezone?: string },\n  ): any {\n    if (!this.CronClass) {\n      throw new Error(\n        'CronerScheduler not initialized. Ensure CronAdapter calls init() ' +\n          'or pass the croner module to the constructor.',\n      )\n    }\n    const job = new this.CronClass(\n      expression,\n      { timezone: options?.timezone, protect: true },\n      callback,\n    )\n    this.jobs.push(job)\n    return job\n  }\n\n  stop(handle: any): void {\n    handle?.stop?.()\n    this.jobs = this.jobs.filter((j) => j !== handle)\n  }\n\n  stopAll(): void {\n    for (const job of this.jobs) {\n      job?.stop?.()\n    }\n    this.jobs = []\n  }\n}\n\n// ── IntervalScheduler (zero-dep fallback) ───────────────────────────────\n\n/**\n * Lightweight fallback scheduler using `setInterval`.\n * Converts common cron patterns to millisecond intervals.\n *\n * Use for development or simple recurring tasks. For production,\n * use CronerScheduler or implement a custom CronScheduler.\n *\n * Limitations:\n * - No timezone support\n * - No day-of-week, day-of-month, or month-specific scheduling\n * - Complex expressions fall back to 1-hour intervals\n * - Timer drift over long periods\n *\n * @example\n * ```ts\n * import { CronAdapter, IntervalScheduler } from '@forinda/kickjs-cron'\n *\n * new CronAdapter({\n *   services: [ReportService],\n *   scheduler: new IntervalScheduler(),\n * })\n * ```\n */\nexport class IntervalScheduler implements CronScheduler {\n  private timers: NodeJS.Timeout[] = []\n\n  schedule(\n    expression: string,\n    callback: () => void | Promise<void>,\n    options?: { timezone?: string },\n  ): NodeJS.Timeout {\n    const intervalMs = cronToMs(expression)\n    if (intervalMs === null) {\n      throw new Error(`Invalid cron expression: \"${expression}\"`)\n    }\n    if (options?.timezone) {\n      log.warn(\n        'IntervalScheduler does not support timezones. ' +\n          'Install croner and use CronerScheduler for timezone support.',\n      )\n    }\n    const timer = setInterval(async () => {\n      try {\n        await callback()\n      } catch {\n        // Swallowed — errors are handled by CronAdapter.runJob\n      }\n    }, intervalMs)\n    this.timers.push(timer)\n    return timer\n  }\n\n  stop(handle: NodeJS.Timeout): void {\n    clearInterval(handle)\n    this.timers = this.timers.filter((t) => t !== handle)\n  }\n\n  stopAll(): void {\n    for (const timer of this.timers) {\n      clearInterval(timer)\n    }\n    this.timers = []\n  }\n}\n\n// ── Lightweight cron-to-ms parser ───────────────────────────────────────\n\n// Converts simplified cron expressions to millisecond intervals.\n// Used internally by IntervalScheduler.\nfunction cronToMs(expression: string): number | null {\n  const parts = expression.trim().split(/\\s+/)\n\n  let minute: string, hour: string\n  if (parts.length === 5) {\n    ;[minute, hour] = parts\n  } else if (parts.length === 6) {\n    ;[, minute, hour] = parts\n  } else {\n    return null\n  }\n\n  // Every N seconds: */N * * * * *\n  if (parts.length === 6 && parts[0].startsWith('*/')) {\n    const secs = parseInt(parts[0].slice(2), 10)\n    if (!isNaN(secs) && secs > 0) return secs * 1000\n  }\n\n  // Every N minutes: */N * * * *\n  if (minute.startsWith('*/')) {\n    const mins = parseInt(minute.slice(2), 10)\n    if (!isNaN(mins) && mins > 0) return mins * 60 * 1000\n  }\n\n  // Every hour: 0 * * * *\n  if (minute === '0' && hour === '*') return 60 * 60 * 1000\n\n  // Every N hours: 0 */N * * *\n  if (minute === '0' && hour.startsWith('*/')) {\n    const hrs = parseInt(hour.slice(2), 10)\n    if (!isNaN(hrs) && hrs > 0) return hrs * 60 * 60 * 1000\n  }\n\n  // Every minute: * * * * *\n  if (minute === '*' && hour === '*') return 60 * 1000\n\n  // Daily: 0 0 * * * or 0 N * * *\n  if (/^\\d+$/.test(minute) && /^\\d+$/.test(hour)) {\n    return 24 * 60 * 60 * 1000\n  }\n\n  // Fallback\n  log.warn(\n    `Complex cron \"${expression}\" — using 1h interval. ` +\n      'Install croner and use CronerScheduler for exact scheduling.',\n  )\n  return 60 * 60 * 1000\n}\n","import {\n  Logger,\n  type AppAdapter,\n  type Container,\n  getCronJobs,\n  type CronJobMeta,\n} from '@forinda/kickjs-core'\n\nimport { type CronScheduler, CronerScheduler, IntervalScheduler } from './scheduler'\n\nconst log = Logger.for('CronAdapter')\n\n// ── CronAdapter Options ─────────────────────────────────────────────────\n\nexport interface CronAdapterOptions {\n  /**\n   * Service classes that contain @Cron decorated methods.\n   * Must also be decorated with @Service() for DI resolution.\n   */\n  services: any[]\n\n  /** Enable/disable all cron jobs (default: true) */\n  enabled?: boolean\n\n  /**\n   * Scheduler backend. Defaults to CronerScheduler (production-grade)\n   * with automatic fallback to IntervalScheduler if croner is not installed.\n   *\n   * Built-in:\n   * - `new CronerScheduler()` — full cron syntax, timezones, DST (requires `croner`)\n   * - `new IntervalScheduler()` — zero-dep, setInterval-based (dev/simple tasks)\n   *\n   * Or implement `CronScheduler` for node-cron, node-schedule, cloud schedulers, etc.\n   */\n  scheduler?: CronScheduler\n}\n\n// ── CronAdapter ─────────────────────────────────────────────────────────\n\n/**\n * Cron adapter — scans services for @Cron decorated methods and\n * schedules them using a pluggable scheduler backend.\n *\n * By default, tries `croner` for production-grade scheduling. Falls back\n * to `setInterval` if croner is not installed.\n *\n * @example\n * ```ts\n * import { CronAdapter } from '@forinda/kickjs-cron'\n *\n * // Auto-detect best available scheduler\n * bootstrap({\n *   adapters: [\n *     new CronAdapter({ services: [ReportService, CleanupService] }),\n *   ],\n * })\n *\n * // Explicit production scheduler\n * import { CronerScheduler } from '@forinda/kickjs-cron'\n *\n * bootstrap({\n *   adapters: [\n *     new CronAdapter({\n *       services: [ReportService],\n *       scheduler: new CronerScheduler(),\n *     }),\n *   ],\n * })\n *\n * // Custom scheduler\n * import { NodeCronScheduler } from './my-scheduler'\n *\n * bootstrap({\n *   adapters: [\n *     new CronAdapter({\n *       services: [ReportService],\n *       scheduler: new NodeCronScheduler(),\n *     }),\n *   ],\n * })\n * ```\n */\nexport class CronAdapter implements AppAdapter {\n  name = 'CronAdapter'\n  private scheduler: CronScheduler | null = null\n  private enabled: boolean\n\n  constructor(private options: CronAdapterOptions) {\n    this.enabled = options.enabled ?? true\n  }\n\n  async afterStart(_server: any, container: Container): Promise<void> {\n    if (!this.enabled) {\n      log.info('Cron disabled')\n      return\n    }\n\n    this.scheduler = await this.resolveScheduler()\n\n    let totalJobs = 0\n\n    for (const ServiceClass of this.options.services) {\n      const jobs = getCronJobs(ServiceClass)\n      if (jobs.length === 0) continue\n\n      const instance = container.resolve(ServiceClass)\n\n      for (const job of jobs) {\n        const label = job.description ?? `${ServiceClass.name}.${job.handlerName}`\n\n        try {\n          if (job.runOnInit) {\n            this.runJob(instance, job, label)\n          }\n\n          this.scheduler.schedule(job.expression, () => this.runJob(instance, job, label), {\n            timezone: job.timezone,\n          })\n\n          totalJobs++\n          log.info(\n            `Scheduled: ${label} (${job.expression}${job.timezone ? ` [${job.timezone}]` : ''})`,\n          )\n        } catch (err: any) {\n          log.error({ err }, `Failed to schedule: ${label}`)\n        }\n      }\n    }\n\n    if (totalJobs > 0) {\n      const schedulerName = this.scheduler.constructor.name\n      log.info(`${totalJobs} cron job(s) active [${schedulerName}]`)\n    }\n  }\n\n  private async resolveScheduler(): Promise<CronScheduler> {\n    if (this.options.scheduler) {\n      return this.options.scheduler\n    }\n\n    // Try CronerScheduler first (production default)\n    const croner = new CronerScheduler()\n    try {\n      await croner.init()\n      log.info('Using CronerScheduler (production)')\n      return croner\n    } catch {\n      log.warn(\n        'croner not installed — using IntervalScheduler (limited cron support). ' +\n          'For production: pnpm add croner',\n      )\n      return new IntervalScheduler()\n    }\n  }\n\n  private async runJob(instance: any, job: CronJobMeta, label: string): Promise<void> {\n    try {\n      await instance[job.handlerName]()\n    } catch (err: any) {\n      log.error({ err }, `Cron job failed: ${label}`)\n    }\n  }\n\n  shutdown(): void {\n    if (this.scheduler) {\n      this.scheduler.stopAll()\n    }\n    log.info('All cron jobs stopped')\n  }\n}\n"],"mappings":"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","names":["Cron","getCronJobs","CRON_META","Logger","log","Logger","for","CronerScheduler","CronClass","jobs","cronerModule","Cron","init","mod","Error","schedule","expression","callback","options","job","timezone","protect","push","stop","handle","filter","j","stopAll","IntervalScheduler","timers","intervalMs","cronToMs","warn","timer","setInterval","clearInterval","t","parts","trim","split","minute","hour","length","startsWith","secs","parseInt","slice","isNaN","mins","hrs","test","Logger","getCronJobs","log","Logger","for","CronAdapter","name","scheduler","enabled","options","afterStart","_server","container","info","resolveScheduler","totalJobs","ServiceClass","services","jobs","getCronJobs","length","instance","resolve","job","label","description","handlerName","runOnInit","runJob","schedule","expression","timezone","err","error","schedulerName","croner","CronerScheduler","init","warn","IntervalScheduler","shutdown","stopAll"]}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@forinda/kickjs-cron",
+  "version": "1.1.0",
+  "description": "Production-grade cron job scheduling with pluggable backends for KickJS",
+  "keywords": [
+    "kickjs",
+    "cron",
+    "scheduler",
+    "jobs",
+    "croner",
+    "node-cron",
+    "typescript",
+    "decorators",
+    "production",
+    "timezone"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "reflect-metadata": "^0.2.2",
+    "@forinda/kickjs-core": "1.1.0"
+  },
+  "peerDependencies": {
+    "croner": "^9.0.0 || ^10.0.0"
+  },
+  "peerDependenciesMeta": {
+    "croner": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.5.2",
+    "croner": "^10.0.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "Felix Orinda",
+  "engines": {
+    "node": ">=20.0"
+  },
+  "homepage": "https://forinda.github.io/kick-js/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/forinda/kick-js.git",
+    "directory": "packages/cron"
+  },
+  "bugs": {
+    "url": "https://github.com/forinda/kick-js/issues"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  }
+}