@objectstack/service-job 4.0.4 → 4.1.0

package/dist/index.d.cts

@@ -33,40 +33,101 @@ declare class IntervalJobAdapter implements IJobService {
     private executeJob;
 }
 
+interface JobEngineLike {
+    find(object: string, options?: any): Promise<any[]>;
+    insert(object: string, data: any, options?: any): Promise<any>;
+    update(object: string, idOrData: any, dataOrOptions?: any, options?: any): Promise<any>;
+    delete?(object: string, options?: any): Promise<any>;
+}
+interface JobLoggerLike {
+    info(msg: string, meta?: unknown): void;
+    warn(msg: string, meta?: unknown): void;
+    error?(msg: string, meta?: unknown): void;
+}
+interface DbJobAdapterOptions {
+    /** Maximum executions kept in memory per job (default 100) */
+    maxExecutions?: number;
+    /** Soft cap on sys_job_run rows recorded per job (defaults to none — handled by retention jobs) */
+    recordRuns?: boolean;
+}
+/**
+ * DbJobAdapter — IJobService that persists job registry and execution
+ * history to ObjectQL while delegating timer mechanics to
+ * `IntervalJobAdapter`. Cron is delegated to `CronJobAdapter` callers
+ * supplied via {@link withCron}.
+ *
+ * Persisted side effects:
+ *   - `schedule(name, …)` upserts a `sys_job` row (active=true)
+ *   - `cancel(name)` marks the row inactive
+ *   - every execution writes a `sys_job_run` row
+ *   - every execution updates `sys_job.last_run_at / last_status / run_count / failure_count`
+ *
+ * The persistence is best-effort: a DB failure is logged but does not
+ * break job execution. This keeps a healthy job system resilient to
+ * transient storage hiccups.
+ */
+declare class DbJobAdapter implements IJobService {
+    private readonly inner;
+    private readonly cron?;
+    private readonly engine;
+    private readonly logger?;
+    private readonly recordRuns;
+    constructor(args: {
+        engine: JobEngineLike;
+        logger?: JobLoggerLike;
+        options?: DbJobAdapterOptions;
+        cron?: IJobService;
+    });
+    schedule(name: string, schedule: JobSchedule, handler: JobHandler): Promise<void>;
+    cancel(name: string): Promise<void>;
+    trigger(name: string, data?: unknown): Promise<void>;
+    getExecutions(name: string, limit?: number): Promise<JobExecution[]>;
+    listJobs(): Promise<string[]>;
+    replay(name: string, data?: unknown): Promise<void>;
+    listExecutionsByStatus(status: JobExecution['status'], limit?: number): Promise<JobExecution[]>;
+    destroy(): Promise<void>;
+    private wrap;
+    private startRun;
+    private finishRun;
+    private upsertJobRow;
+    private setActive;
+    private bumpJob;
+}
+
 /**
  * Configuration options for the JobServicePlugin.
  */
 interface JobServicePluginOptions {
-    /** Job adapter type (default: 'interval') */
-    adapter?: 'interval' | 'cron';
+    /**
+     * Job adapter type.
+     *  - 'auto' (default): use DbJobAdapter when objectql engine available, else IntervalJobAdapter
+     *  - 'db': require objectql; persists schedules and runs to sys_job/sys_job_run
+     *  - 'interval': in-memory IntervalJobAdapter (legacy, non-durable)
+     *  - 'cron': in-memory CronJobAdapter using `croner`
+     */
+    adapter?: 'auto' | 'db' | 'interval' | 'cron';
     /** Options for the interval job adapter */
     interval?: IntervalJobAdapterOptions;
+    /** Options for the DB adapter */
+    db?: DbJobAdapterOptions;
+    /** Whether to also wire CronJobAdapter for cron schedules (default: true when available) */
+    enableCron?: boolean;
 }
 /**
  * JobServicePlugin — Production IJobService implementation.
  *
- * Registers a job scheduler with the kernel during the init phase.
- * Supports setInterval-based and cron-based adapters.
- *
- * @example
- * ```ts
- * import { ObjectKernel } from '@objectstack/core';
- * import { JobServicePlugin } from '@objectstack/service-job';
- *
- * const kernel = new ObjectKernel();
- * kernel.use(new JobServicePlugin({ adapter: 'interval' }));
- * await kernel.bootstrap();
- *
- * const job = kernel.getService('job');
- * await job.schedule('cleanup', { type: 'interval', intervalMs: 60000 }, handler);
- * ```
+ * Default behaviour: registers a `DbJobAdapter` when the ObjectQL engine is
+ * available (persisting registry + execution history to `sys_job` and
+ * `sys_job_run`), falling back to in-memory `IntervalJobAdapter` otherwise.
+ * Cron schedules are routed to `CronJobAdapter` (croner-backed).
  */
 declare class JobServicePlugin implements Plugin {
     name: string;
     version: string;
     type: string;
     private readonly options;
-    private adapter?;
+    private dbAdapter?;
+    private intervalAdapter?;
     constructor(options?: JobServicePluginOptions);
     init(ctx: PluginContext): Promise<void>;
     destroy(): Promise<void>;
@@ -78,27 +139,29 @@ declare class JobServicePlugin implements Plugin {
 interface CronJobAdapterOptions {
     /** Timezone for cron expressions (default: 'UTC') */
     timezone?: string;
+    /** Maximum execution history per job (default: 100) */
+    maxExecutions?: number;
 }
 /**
- * Cron-based job adapter skeleton implementing IJobService.
- *
- * This is a placeholder for future cron integration (e.g., `node-cron` or `croner`).
- * Concrete implementation will parse cron expressions and schedule jobs accordingly.
- *
- * @example
- * ```ts
- * const scheduler = new CronJobAdapter({ timezone: 'America/New_York' });
- * await scheduler.schedule('nightly-cleanup', { type: 'cron', expression: '0 0 * * *' }, handler);
- * ```
+ * Cron-based job adapter implementing IJobService using the `croner`
+ * library. Honours per-job timezones, supports the standard 5-field cron
+ * syntax, and falls back to setInterval / setTimeout for `interval` and
+ * `once` schedule types (so a single CronJobAdapter can serve as the
+ * "real" production job runner).
  */
 declare class CronJobAdapter implements IJobService {
-    private readonly timezone;
+    private readonly defaultTimezone;
+    private readonly maxExecutions;
+    private readonly jobs;
     constructor(options?: CronJobAdapterOptions);
-    schedule(_name: string, _schedule: JobSchedule, _handler: JobHandler): Promise<void>;
-    cancel(_name: string): Promise<void>;
-    trigger(_name: string, _data?: unknown): Promise<void>;
-    getExecutions(_name: string, _limit?: number): Promise<JobExecution[]>;
+    schedule(name: string, schedule: JobSchedule, handler: JobHandler): Promise<void>;
+    cancel(name: string): Promise<void>;
+    trigger(name: string, data?: unknown): Promise<void>;
+    getExecutions(name: string, limit?: number): Promise<JobExecution[]>;
     listJobs(): Promise<string[]>;
+    /** Stop all timers — call from plugin destroy. */
+    destroy(): Promise<void>;
+    private execute;
 }
 
-export { CronJobAdapter, type CronJobAdapterOptions, IntervalJobAdapter, type IntervalJobAdapterOptions, JobServicePlugin, type JobServicePluginOptions };
+export { CronJobAdapter, type CronJobAdapterOptions, DbJobAdapter, type DbJobAdapterOptions, IntervalJobAdapter, type IntervalJobAdapterOptions, type JobEngineLike, type JobLoggerLike, JobServicePlugin, type JobServicePluginOptions };

package/dist/index.d.ts

@@ -33,40 +33,101 @@ declare class IntervalJobAdapter implements IJobService {
     private executeJob;
 }
 
+interface JobEngineLike {
+    find(object: string, options?: any): Promise<any[]>;
+    insert(object: string, data: any, options?: any): Promise<any>;
+    update(object: string, idOrData: any, dataOrOptions?: any, options?: any): Promise<any>;
+    delete?(object: string, options?: any): Promise<any>;
+}
+interface JobLoggerLike {
+    info(msg: string, meta?: unknown): void;
+    warn(msg: string, meta?: unknown): void;
+    error?(msg: string, meta?: unknown): void;
+}
+interface DbJobAdapterOptions {
+    /** Maximum executions kept in memory per job (default 100) */
+    maxExecutions?: number;
+    /** Soft cap on sys_job_run rows recorded per job (defaults to none — handled by retention jobs) */
+    recordRuns?: boolean;
+}
+/**
+ * DbJobAdapter — IJobService that persists job registry and execution
+ * history to ObjectQL while delegating timer mechanics to
+ * `IntervalJobAdapter`. Cron is delegated to `CronJobAdapter` callers
+ * supplied via {@link withCron}.
+ *
+ * Persisted side effects:
+ *   - `schedule(name, …)` upserts a `sys_job` row (active=true)
+ *   - `cancel(name)` marks the row inactive
+ *   - every execution writes a `sys_job_run` row
+ *   - every execution updates `sys_job.last_run_at / last_status / run_count / failure_count`
+ *
+ * The persistence is best-effort: a DB failure is logged but does not
+ * break job execution. This keeps a healthy job system resilient to
+ * transient storage hiccups.
+ */
+declare class DbJobAdapter implements IJobService {
+    private readonly inner;
+    private readonly cron?;
+    private readonly engine;
+    private readonly logger?;
+    private readonly recordRuns;
+    constructor(args: {
+        engine: JobEngineLike;
+        logger?: JobLoggerLike;
+        options?: DbJobAdapterOptions;
+        cron?: IJobService;
+    });
+    schedule(name: string, schedule: JobSchedule, handler: JobHandler): Promise<void>;
+    cancel(name: string): Promise<void>;
+    trigger(name: string, data?: unknown): Promise<void>;
+    getExecutions(name: string, limit?: number): Promise<JobExecution[]>;
+    listJobs(): Promise<string[]>;
+    replay(name: string, data?: unknown): Promise<void>;
+    listExecutionsByStatus(status: JobExecution['status'], limit?: number): Promise<JobExecution[]>;
+    destroy(): Promise<void>;
+    private wrap;
+    private startRun;
+    private finishRun;
+    private upsertJobRow;
+    private setActive;
+    private bumpJob;
+}
+
 /**
  * Configuration options for the JobServicePlugin.
  */
 interface JobServicePluginOptions {
-    /** Job adapter type (default: 'interval') */
-    adapter?: 'interval' | 'cron';
+    /**
+     * Job adapter type.
+     *  - 'auto' (default): use DbJobAdapter when objectql engine available, else IntervalJobAdapter
+     *  - 'db': require objectql; persists schedules and runs to sys_job/sys_job_run
+     *  - 'interval': in-memory IntervalJobAdapter (legacy, non-durable)
+     *  - 'cron': in-memory CronJobAdapter using `croner`
+     */
+    adapter?: 'auto' | 'db' | 'interval' | 'cron';
     /** Options for the interval job adapter */
     interval?: IntervalJobAdapterOptions;
+    /** Options for the DB adapter */
+    db?: DbJobAdapterOptions;
+    /** Whether to also wire CronJobAdapter for cron schedules (default: true when available) */
+    enableCron?: boolean;
 }
 /**
  * JobServicePlugin — Production IJobService implementation.
  *
- * Registers a job scheduler with the kernel during the init phase.
- * Supports setInterval-based and cron-based adapters.
- *
- * @example
- * ```ts
- * import { ObjectKernel } from '@objectstack/core';
- * import { JobServicePlugin } from '@objectstack/service-job';
- *
- * const kernel = new ObjectKernel();
- * kernel.use(new JobServicePlugin({ adapter: 'interval' }));
- * await kernel.bootstrap();
- *
- * const job = kernel.getService('job');
- * await job.schedule('cleanup', { type: 'interval', intervalMs: 60000 }, handler);
- * ```
+ * Default behaviour: registers a `DbJobAdapter` when the ObjectQL engine is
+ * available (persisting registry + execution history to `sys_job` and
+ * `sys_job_run`), falling back to in-memory `IntervalJobAdapter` otherwise.
+ * Cron schedules are routed to `CronJobAdapter` (croner-backed).
  */
 declare class JobServicePlugin implements Plugin {
     name: string;
     version: string;
     type: string;
     private readonly options;
-    private adapter?;
+    private dbAdapter?;
+    private intervalAdapter?;
     constructor(options?: JobServicePluginOptions);
     init(ctx: PluginContext): Promise<void>;
     destroy(): Promise<void>;
@@ -78,27 +139,29 @@ declare class JobServicePlugin implements Plugin {
 interface CronJobAdapterOptions {
     /** Timezone for cron expressions (default: 'UTC') */
     timezone?: string;
+    /** Maximum execution history per job (default: 100) */
+    maxExecutions?: number;
 }
 /**
- * Cron-based job adapter skeleton implementing IJobService.
- *
- * This is a placeholder for future cron integration (e.g., `node-cron` or `croner`).
- * Concrete implementation will parse cron expressions and schedule jobs accordingly.
- *
- * @example
- * ```ts
- * const scheduler = new CronJobAdapter({ timezone: 'America/New_York' });
- * await scheduler.schedule('nightly-cleanup', { type: 'cron', expression: '0 0 * * *' }, handler);
- * ```
+ * Cron-based job adapter implementing IJobService using the `croner`
+ * library. Honours per-job timezones, supports the standard 5-field cron
+ * syntax, and falls back to setInterval / setTimeout for `interval` and
+ * `once` schedule types (so a single CronJobAdapter can serve as the
+ * "real" production job runner).
  */
 declare class CronJobAdapter implements IJobService {
-    private readonly timezone;
+    private readonly defaultTimezone;
+    private readonly maxExecutions;
+    private readonly jobs;
     constructor(options?: CronJobAdapterOptions);
-    schedule(_name: string, _schedule: JobSchedule, _handler: JobHandler): Promise<void>;
-    cancel(_name: string): Promise<void>;
-    trigger(_name: string, _data?: unknown): Promise<void>;
-    getExecutions(_name: string, _limit?: number): Promise<JobExecution[]>;
+    schedule(name: string, schedule: JobSchedule, handler: JobHandler): Promise<void>;
+    cancel(name: string): Promise<void>;
+    trigger(name: string, data?: unknown): Promise<void>;
+    getExecutions(name: string, limit?: number): Promise<JobExecution[]>;
     listJobs(): Promise<string[]>;
+    /** Stop all timers — call from plugin destroy. */
+    destroy(): Promise<void>;
+    private execute;
 }
 
-export { CronJobAdapter, type CronJobAdapterOptions, IntervalJobAdapter, type IntervalJobAdapterOptions, JobServicePlugin, type JobServicePluginOptions };
+export { CronJobAdapter, type CronJobAdapterOptions, DbJobAdapter, type DbJobAdapterOptions, IntervalJobAdapter, type IntervalJobAdapterOptions, type JobEngineLike, type JobLoggerLike, JobServicePlugin, type JobServicePluginOptions };