@orion-js/dogs 4.3.5 → 4.4.0

package/dist/index.d.ts

@@ -1,445 +1,14 @@
-import * as _orion_js_schema from '@orion-js/schema';
-import { SchemaInAnyOrionForm, Blackbox, InferSchemaType } from '@orion-js/schema';
-import { OrionLogger } from '@orion-js/logger';
-import { Collection, MongoDB } from '@orion-js/mongodb';
-
-/**
- * Base type for schedule params that varies based on schema presence
- */
-type ScheduleJobParamsType<TParamsSchema extends SchemaInAnyOrionForm> = TParamsSchema extends undefined ? {
-    params?: Blackbox;
-} : {
-    params: InferSchemaType<TParamsSchema>;
-};
-/**
- * Common options shared by all schedule job variants (without name)
- */
-type ScheduleJobCommonOptions = {
-    priority?: number;
-    uniqueIdentifier?: string;
-};
-/**
- * Schedule options without name - used by job definition's schedule method.
- * This is a distributive type that properly handles runIn/runAt variants.
- */
-type ScheduleJobOptionsWithoutName<TParamsSchema extends SchemaInAnyOrionForm = any> = (ScheduleJobCommonOptions & ScheduleJobParamsType<TParamsSchema> & {
-    runIn: number;
-}) | (ScheduleJobCommonOptions & ScheduleJobParamsType<TParamsSchema> & {
-    runAt: Date;
-}) | (ScheduleJobCommonOptions & ScheduleJobParamsType<TParamsSchema>);
-/**
- * Full schedule options including job name - used by direct scheduleJob calls
- */
-type ScheduleJobOptions<TParamsSchema extends SchemaInAnyOrionForm = any> = ScheduleJobOptionsWithoutName<TParamsSchema> & {
-    name: string;
-};
-/**
- * Legacy type aliases for backwards compatibility
- */
-type ScheduleJobOptionsBase<TParamsSchema extends SchemaInAnyOrionForm> = {
-    name: string;
-    priority?: number;
-    uniqueIdentifier?: string;
-} & ScheduleJobParamsType<TParamsSchema>;
-type ScheduleJobOptionsRunIn<TParamsSchema extends SchemaInAnyOrionForm> = ScheduleJobOptionsBase<TParamsSchema> & {
-    runIn: number;
-};
-type ScheduleJobOptionsRunAt<TParamsSchema extends SchemaInAnyOrionForm> = ScheduleJobOptionsBase<TParamsSchema> & {
-    runAt: Date;
-};
-interface ScheduleJobRecordOptions {
-    name: string;
-    params: Blackbox;
-    nextRunAt: Date;
-    priority: number;
-    uniqueIdentifier?: string;
-}
-type ScheduleJobsOptions<TParamsSchema extends SchemaInAnyOrionForm = any> = ScheduleJobOptions<TParamsSchema>[];
-interface ScheduleJobsResult {
-    scheduledCount: number;
-    skippedCount: number;
-    errors: Array<{
-        index: number;
-        error: Error;
-        job: ScheduleJobOptions;
-    }>;
-}
-
-declare const HistoryRecordSchema: {
-    _id: {
-        type: "string";
-    };
-    jobId: {
-        type: "string";
-    };
-    executionId: {
-        type: "string";
-    };
-    jobName: {
-        type: "string";
-    };
-    type: {
-        type: "string";
-    };
-    priority: {
-        type: "number";
-    };
-    tries: {
-        type: "number";
-    };
-    uniqueIdentifier: {
-        type: "string";
-        optional: true;
-    };
-    startedAt: {
-        type: "date";
-    };
-    endedAt: {
-        type: "date";
-    };
-    duration: {
-        type: "number";
-    };
-    expiresAt: {
-        type: "date";
-        optional: true;
-    };
-    status: {
-        type: "string";
-        enum: string[];
-    };
-    errorMessage: {
-        type: "string";
-        optional: true;
-    };
-    params: {
-        type: "blackbox";
-        optional: true;
-    };
-    result: {
-        type: "any";
-        optional: true;
-    };
-};
-type HistoryRecord = InferSchemaType<typeof HistoryRecordSchema>;
-
-/**
- * Enum representing the status of a job record.
- * - 'pending': Job is active and can be executed (default for existing records)
- * - 'maxTriesReached': Job has exhausted all retry attempts and won't be executed
- */
-declare const JobStatusEnum: _orion_js_schema.FieldType<"pending" | "maxTriesReached">;
-declare const JobRecordSchema: {
-    _id: {
-        type: "string";
-    };
-    jobName: {
-        type: "string";
-    };
-    type: {
-        type: _orion_js_schema.FieldType<"recurrent" | "event">;
-    };
-    priority: {
-        type: "number";
-    };
-    uniqueIdentifier: {
-        type: "string";
-        optional: true;
-    };
-    nextRunAt: {
-        type: "date";
-    };
-    lastRunAt: {
-        type: "date";
-        optional: true;
-    };
-    lockedUntil: {
-        type: "date";
-        optional: true;
-    };
-    tries: {
-        type: "number";
-        optional: true;
-    };
-    params: {
-        type: "blackbox";
-        optional: true;
-    };
-    /**
-     * Status of the job. Optional for backwards compatibility with existing records.
-     * Records without this field are treated as 'pending'.
-     */
-    status: {
-        type: _orion_js_schema.FieldType<"pending" | "maxTriesReached">;
-        optional: true;
-    };
-};
-type JobRecord = InferSchemaType<typeof JobRecordSchema>;
-
-interface JobToRun {
-    jobId: string;
-    executionId: string;
-    name: string;
-    type: 'event' | 'recurrent';
-    params: Blackbox;
-    tries: number;
-    lockTime: number;
-    priority: number;
-    uniqueIdentifier?: string;
-    wasStale?: boolean;
-}
-interface ExecutionContext {
-    record: JobToRun;
-    definition: JobDefinition;
-    tries: number;
-    logger: OrionLogger;
-    extendLockTime: (extraTime: number) => Promise<void>;
-    clearStaleTimeout: () => void;
-}
-interface WorkerInstance {
-    running: boolean;
-    workerIndex: number;
-    stop: () => Promise<void>;
-    respawn: () => Promise<void>;
-    promise?: Promise<any>;
-}
-interface WorkersInstance {
-    running: boolean;
-    workersCount: number;
-    workers: WorkerInstance[];
-    runningJobsByName: Map<string, number>;
-    jobAcquisitionLock: Promise<void>;
-    /**
-     * Stop all workers and wait for them to finish
-     */
-    stop: () => Promise<void>;
-}
-
-interface JobRetryResultBase {
-    action: 'retry' | 'dismiss';
-}
-type JobRetryResultRunIn = JobRetryResultBase & {
-    runIn: number;
-};
-type JobRetryResultRunAt = JobRetryResultBase & {
-    runAt: Date;
-};
-type JobRetryResult = JobRetryResultRunIn | JobRetryResultRunAt | JobRetryResultBase;
-interface BaseJobDefinition {
-    /**
-     * Called if the job fails.
-     */
-    onError?: (error: Error, params: Blackbox, context: ExecutionContext) => Promise<JobRetryResult>;
-    /**
-     * Called if the job locktime is expired. The job will be executed again.
-     */
-    onStale?: (params: Blackbox, context: ExecutionContext) => Promise<void>;
-    /**
-     * Save the executions of the job time in milliseconds. Default is 1 week. Set to 0 to disable.
-     */
-    saveExecutionsFor?: number;
-    /**
-     * The name of the job.
-     * This is set automatically when the job is passed to startWorkers.
-     */
-    jobName?: string;
-    /**
-     * Time in milliseconds to lock this specific job for execution.
-     * Overrides the defaultLockTime set in startWorkers config.
-     * If not set, the defaultLockTime from config will be used.
-     */
-    lockTime?: number;
-    /**
-     * Maximum number of tries for this specific job before it is marked as 'maxTriesReached'.
-     * Overrides the global maxTries set in startWorkers config.
-     * If not set, the global maxTries from config will be used.
-     */
-    maxTries?: number;
-}
-interface RecurrentJobDefinition extends BaseJobDefinition {
-    /**
-     * Type of the job.
-     */
-    type: 'recurrent';
-    /**
-     * A function executed after each execution that returns the date of the next run.
-     */
-    getNextRun?: () => Date;
-    /**
-     * Run every x milliseconds. This will be ignored if getNextRun is defined.
-     */
-    runEvery?: number;
-    /**
-     * Cron expression used to calculate the next run. Requires timezone.
-     */
-    cron?: string;
-    /**
-     * IANA timezone used to calculate cron-based schedules.
-     */
-    timezone?: string;
-    /**
-     * The priority of the job. Higher is more priority. Default is 100.
-     */
-    priority?: number;
-    /**
-     * The function to execute when the job is executed.
-     */
-    resolve: (_: any, context: ExecutionContext) => Promise<Blackbox | void>;
-}
-interface EventJobDefinition<TParamsSchema extends SchemaInAnyOrionForm = any> extends BaseJobDefinition {
-    /**
-     * Type of the job.
-     */
-    type: 'event';
-    /**
-     * Schedule of the job. Supports optional runIn (milliseconds) or runAt (Date) for delayed execution.
-     */
-    schedule: (options: ScheduleJobOptionsWithoutName<TParamsSchema>) => Promise<void>;
-    /**
-     * Schedule multiple jobs at once. Each job supports optional runIn or runAt for delayed execution.
-     */
-    scheduleJobs: (jobs: Array<ScheduleJobOptionsWithoutName<TParamsSchema>>) => Promise<ScheduleJobsResult>;
-    /**
-     * The schema of the params of the job.
-     */
-    params?: TParamsSchema;
-    /**
-     * Maximum number of executions of this job that can run in parallel on the same server.
-     * If not set, the job can use all available workers on the current server.
-     */
-    maxParallelExecutionsPerServer?: number;
-    /**
-     * The function to execute when the job is executed.
-     */
-    resolve: (params: InferSchemaType<TParamsSchema>, context: ExecutionContext) => Promise<any>;
-}
-type CreateEventJobOptions<TParamsSchema extends SchemaInAnyOrionForm = any> = Omit<EventJobDefinition<TParamsSchema>, 'type' | 'schedule' | 'scheduleJobs'>;
-type CreateRecurrentJobBaseOptions = Omit<RecurrentJobDefinition, 'type' | 'runEvery' | 'cron' | 'timezone'>;
-type CreateRecurrentJobRunEveryOptions = CreateRecurrentJobBaseOptions & {
-    /**
-     * Run every x milliseconds.
-     * Accepts https://github.com/jkroso/parse-duration strings.
-     */
-    runEvery: number | string;
-    cron?: never;
-    timezone?: string;
-};
-type CreateRecurrentJobCronOptions = CreateRecurrentJobBaseOptions & {
-    /**
-     * Cron expression used to calculate the next run.
-     */
-    cron: string;
-    /**
-     * IANA timezone used to calculate cron-based schedules.
-     */
-    timezone: string;
-    runEvery?: never;
-};
-type CreateRecurrentJobOptions = CreateRecurrentJobRunEveryOptions | CreateRecurrentJobCronOptions;
-type CreateJobOptions<TParamsSchema extends SchemaInAnyOrionForm = any> = CreateEventJobOptions<TParamsSchema> | CreateRecurrentJobOptions;
-type JobDefinition<TParamsSchema extends SchemaInAnyOrionForm = any> = RecurrentJobDefinition | EventJobDefinition<TParamsSchema>;
-type JobDefinitionWithName<TParamsSchema extends SchemaInAnyOrionForm = any> = JobDefinition<TParamsSchema> & {
-    name: string;
-};
-interface JobsDefinition {
-    [jobName: string]: JobDefinition;
-}
-
-type LogLevels = 'debug' | 'info' | 'warn' | 'error' | 'none';
-interface StartWorkersConfig {
-    /**
-     * Object map of the jobs that this workers will execute
-     */
-    jobs: JobsDefinition;
-    /**
-     * Maximum number of tries for a job before it is marked as 'maxTriesReached'.
-     * This is a required global default that can be overridden per job definition.
-     */
-    maxTries: number;
-    /**
-     * Callback invoked when a job reaches its maximum tries limit.
-     * Use this to notify administrators (e.g., send an email alert).
-     * The job will remain in the database with status 'maxTriesReached'.
-     */
-    onMaxTriesReached: (job: JobToRun) => Promise<void>;
-    /**
-     * Time in milliseconds to wait between each look without results for a job
-     * to run at the database. Default is 3000.
-     */
-    pollInterval?: number;
-    /**
-     * Time in milliseconds to wait too look for a job after a job execution. Default is 100.
-     */
-    cooldownPeriod?: number;
-    /**
-     * Number of workers to start. Default is 1.
-     */
-    workersCount?: number;
-    /**
-     * Default time in milliseconds to lock a job for execution. Default is 30000 (30 seconds).
-     * If a job is locked for longer than this time, it will be considered as failed.
-     * This is to prevent a job from being executed multiple times at the same time.
-     * You can extend this time inside a job by calling extendLockTime from context.
-     * Individual jobs can override this value by setting their own lockTime.
-     */
-    defaultLockTime?: number;
-}
-
-declare class JobsHistoryRepo {
-    history: Collection<HistoryRecord>;
-    saveExecution(record: MongoDB.WithoutId<HistoryRecord>): Promise<void>;
-    getExecutions(jobName: string, limit?: number, skip?: number): Promise<HistoryRecord[]>;
-}
-
-declare class JobsRepo {
-    jobs: Collection<JobRecord>;
-    getJobAndLock(jobNames: string[], lockTime: number): Promise<JobToRun>;
-    setJobRecordPriority(jobId: string, priority: number): Promise<void>;
-    scheduleNextRun(options: {
-        jobId: string;
-        nextRunAt: Date;
-        resetTries: boolean;
-        priority: number;
-    }): Promise<void>;
-    deleteEventJob(jobId: string): Promise<void>;
-    /**
-     * Marks a job as having reached its maximum tries limit.
-     * The job will remain in the database but won't be picked up for execution.
-     */
-    markJobAsMaxTriesReached(jobId: string): Promise<void>;
-    extendLockTime(jobId: string, extraTime: number): Promise<void>;
-    /**
-     * Updates the lock time for a job to the specified duration from now.
-     * Can be used to both extend or shorten the lock time.
-     */
-    updateLockTime(jobId: string, lockDuration: number): Promise<void>;
-    unlockAllJobs(): Promise<number>;
-    ensureJobRecord(job: JobDefinitionWithName): Promise<void>;
-    scheduleJob(options: ScheduleJobRecordOptions): Promise<void>;
-    scheduleJobs(jobs: ScheduleJobRecordOptions[]): Promise<ScheduleJobsResult>;
-}
-
-declare function Jobs(): (target: any, context: ClassDecoratorContext<any>) => void;
-declare function RecurrentJob(): (method: any, context: ClassFieldDecoratorContext | ClassMethodDecoratorContext) => any;
-declare function RecurrentJob(options: Omit<RecurrentJobDefinition, 'resolve' | 'type'>): (method: any, context: ClassMethodDecoratorContext) => any;
-declare function EventJob(): (method: any, context: ClassFieldDecoratorContext | ClassMethodDecoratorContext) => any;
-declare function EventJob(options: Omit<CreateEventJobOptions<any>, 'resolve'>): (method: any, context: ClassMethodDecoratorContext) => any;
-declare function getServiceJobs(target: any): {
-    [key: string]: JobDefinition;
-};
-
-declare function createEventJob<TParamsSchema extends SchemaInAnyOrionForm>(options: CreateEventJobOptions<TParamsSchema>): EventJobDefinition<TParamsSchema>;
-declare function createRecurrentJob(options: CreateRecurrentJobOptions): RecurrentJobDefinition;
-/**
- * @deprecated Use `createEventJob` or `createRecurrentJob` instead.
- */
-declare const defineJob: (options: CreateJobOptions & {
-    type: "event" | "recurrent";
-}) => JobDefinition;
-
+import { StartWorkersConfig } from './types/StartConfig';
+import { ScheduleJobOptions, ScheduleJobsOptions, ScheduleJobsResult } from './types/Events';
+import { JobsHistoryRepo } from './repos/JobsHistoryRepo';
+import { JobsRepo } from './repos/JobsRepo';
+import { SchemaInAnyOrionForm } from '@orion-js/schema';
+export * from './types';
+export * from './service';
+export * from './defineJob';
 declare const jobsHistoryRepo: JobsHistoryRepo;
 declare const jobsRepo: JobsRepo;
-declare const startWorkers: (config: StartWorkersConfig) => WorkersInstance;
+declare const startWorkers: (config: StartWorkersConfig) => import("./types").WorkersInstance;
 /**
  * @deprecated Use the event job definition.schedule method instead.
  */
@@ -449,5 +18,4 @@ declare const scheduleJob: <TParamsSchema extends SchemaInAnyOrionForm = any>(op
  * @deprecated Use the event job definition.scheduleJobs method instead.
  */
 declare const scheduleJobs: <TParamsSchema extends SchemaInAnyOrionForm = any>(jobs: ScheduleJobsOptions<TParamsSchema>) => Promise<ScheduleJobsResult>;
-
-export { type BaseJobDefinition, type CreateEventJobOptions, type CreateJobOptions, type CreateRecurrentJobCronOptions, type CreateRecurrentJobOptions, type CreateRecurrentJobRunEveryOptions, EventJob, type EventJobDefinition, type ExecutionContext, type HistoryRecord, HistoryRecordSchema, type JobDefinition, type JobDefinitionWithName, type JobRecord, JobRecordSchema, type JobRetryResult, type JobRetryResultBase, type JobRetryResultRunAt, type JobRetryResultRunIn, JobStatusEnum, type JobToRun, Jobs, type JobsDefinition, type LogLevels, RecurrentJob, type RecurrentJobDefinition, type ScheduleJobOptions, type ScheduleJobOptionsBase, type ScheduleJobOptionsRunAt, type ScheduleJobOptionsRunIn, type ScheduleJobOptionsWithoutName, type ScheduleJobRecordOptions, type ScheduleJobsOptions, type ScheduleJobsResult, type StartWorkersConfig, type WorkerInstance, type WorkersInstance, createEventJob, createRecurrentJob, defineJob, getServiceJobs, jobsHistoryRepo, jobsRepo, scheduleJob, scheduleJobs, startWorkers };
+export { startWorkers, scheduleJob, scheduleJobs, jobsHistoryRepo, jobsRepo };

package/dist/index.js

@@ -124,10 +124,12 @@ var JobsRepo = class {
       {
         jobName: { $in: jobNames },
         nextRunAt: { $lte: /* @__PURE__ */ new Date() },
-        $or: [{ lockedUntil: { $exists: false } }, { lockedUntil: { $lte: /* @__PURE__ */ new Date() } }],
-        // Exclude jobs that have reached max tries. Using $ne handles backwards compatibility
-        // since records without the status field will still match (undefined !== 'maxTriesReached')
-        status: { $ne: "maxTriesReached" }
+        $and: [
+          { $or: [{ lockedUntil: { $exists: false } }, { lockedUntil: { $lte: /* @__PURE__ */ new Date() } }] },
+          // Exclude event jobs that have reached max tries. Recurrent jobs keep running even
+          // if old records still have this status from previous versions.
+          { $or: [{ type: { $ne: "event" } }, { status: { $ne: "maxTriesReached" } }] }
+        ]
       },
       {
         $set: { lockedUntil, lastRunAt: /* @__PURE__ */ new Date() },
@@ -180,12 +182,12 @@ var JobsRepo = class {
     await this.jobs.deleteOne({ _id: jobId, type: "event" });
   }
   /**
-   * Marks a job as having reached its maximum tries limit.
+   * Marks an event job as having reached its maximum tries limit.
    * The job will remain in the database but won't be picked up for execution.
    */
   async markJobAsMaxTriesReached(jobId) {
     await this.jobs.updateOne(
-      { _id: jobId },
+      { _id: jobId, type: "event" },
       {
         $set: { status: "maxTriesReached" },
         $unset: { lockedUntil: "" }
@@ -231,6 +233,9 @@ var JobsRepo = class {
           type: job.type,
           priority: job.priority
         },
+        $unset: {
+          status: ""
+        },
         $setOnInsert: {
           nextRunAt: /* @__PURE__ */ new Date()
         }
@@ -553,7 +558,7 @@ var Executor = class {
     return job;
   }
   /**
-   * Determines the effective max tries for a job.
+   * Determines the effective max tries for an event job.
    * Job-specific maxTries takes precedence over the global maxTries from config.
    */
   getEffectiveMaxTries(job, globalMaxTries) {
@@ -561,7 +566,7 @@ var Executor = class {
   }
   /**
    * Handles when a job has reached its maximum retry attempts.
-   * Marks the job in the database and invokes the onMaxTriesReached callback.
+   * Marks the job in the database and invokes the onMaxTriesReached callback when provided.
    */
   async handleMaxTriesReached(jobToRun, onMaxTriesReached) {
     const jobLogger = logger3.addMetadata({
@@ -572,6 +577,7 @@ var Executor = class {
       `Job "${jobToRun.name}" has exceeded max tries (${jobToRun.tries}). Marking as maxTriesReached.`
     );
     await this.jobsRepo.markJobAsMaxTriesReached(jobToRun.jobId);
+    if (!onMaxTriesReached) return;
     try {
       await onMaxTriesReached(jobToRun);
     } catch (callbackError) {
@@ -580,7 +586,7 @@ var Executor = class {
       });
     }
   }
-  async onError(error, job, jobToRun, context, config) {
+  async onError(error, job, jobToRun, context) {
     const scheduleRecurrent = async () => {
       if (job.type === "recurrent") {
         await this.jobsRepo.scheduleNextRun({
@@ -661,10 +667,12 @@ var Executor = class {
   async executeJob(config, jobToRun, respawnWorker) {
     const job = this.getJobDefinition(jobToRun, config.jobs);
     if (!job) return;
-    const effectiveMaxTries = this.getEffectiveMaxTries(job, config.maxTries);
-    if (jobToRun.tries > effectiveMaxTries) {
-      await this.handleMaxTriesReached(jobToRun, config.onMaxTriesReached);
-      return;
+    if (job.type === "event") {
+      const effectiveMaxTries = this.getEffectiveMaxTries(job, config.maxTries);
+      if (typeof effectiveMaxTries === "number" && jobToRun.tries > effectiveMaxTries) {
+        await this.handleMaxTriesReached(jobToRun, config.onMaxTriesReached);
+        return;
+      }
     }
     const effectiveLockTime = this.getEffectiveLockTime(job, jobToRun);
     if (effectiveLockTime !== jobToRun.lockTime) {
@@ -733,7 +741,7 @@ var Executor = class {
             }).catch((saveError) => {
               context.logger.error("Error saving failed execution history", { error: saveError });
             });
-            await this.onError(error, job, jobToRun, context, config);
+            await this.onError(error, job, jobToRun, context);
           }
         });
       } catch (error) {
@@ -920,7 +928,7 @@ var WorkerService = class {
   }
   /**
    * Starts the job workers with the provided configuration.
-   * @param userConfig - Configuration for the workers. Required fields: jobs, maxTries, onMaxTriesReached
+   * @param userConfig - Configuration for the workers. Required field: jobs
    */
   startWorkers(userConfig) {
     const config = {
@@ -992,16 +1000,20 @@ function createEventJob(options) {
   return jobDefinition;
 }
 function createRecurrentJob(options) {
-  if ("cron" in options && options.cron && !options.timezone) {
+  const recurrentOptions = {
+    ...options
+  };
+  delete recurrentOptions.maxTries;
+  if ("cron" in recurrentOptions && recurrentOptions.cron && !recurrentOptions.timezone) {
     throw new Error("Cron recurrent jobs require a timezone");
   }
-  if ("cron" in options && options.cron) {
-    CronExpressionParser2.parse(options.cron, { tz: options.timezone }).next();
+  if ("cron" in recurrentOptions && recurrentOptions.cron) {
+    CronExpressionParser2.parse(recurrentOptions.cron, { tz: recurrentOptions.timezone }).next();
   }
-  const runEvery = "runEvery" in options ? typeof options.runEvery === "string" ? parse(options.runEvery) : options.runEvery : void 0;
+  const runEvery = "runEvery" in recurrentOptions ? typeof recurrentOptions.runEvery === "string" ? parse(recurrentOptions.runEvery) : recurrentOptions.runEvery : void 0;
   const jobDefinition = {
-    ...options,
-    priority: options.priority ?? 100,
+    ...recurrentOptions,
+    priority: recurrentOptions.priority ?? 100,
     type: "recurrent",
     runEvery
   };