@orion-js/dogs 4.3.5 → 4.4.0

package/dist/types/JobRecord.d.ts

@@ -0,0 +1,53 @@
+import { InferSchemaType } from '@orion-js/schema';
+/**
+ * Enum representing the status of a job record.
+ * - 'pending': Job is active and can be executed (default for existing records)
+ * - 'maxTriesReached': Event job has exhausted all retry attempts and won't be executed
+ */
+export declare const JobStatusEnum: import("@orion-js/schema").FieldType<"maxTriesReached" | "pending">;
+export declare const JobRecordSchema: {
+    _id: {
+        type: "string";
+    };
+    jobName: {
+        type: "string";
+    };
+    type: {
+        type: import("@orion-js/schema").FieldType<"event" | "recurrent">;
+    };
+    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: import("@orion-js/schema").FieldType<"maxTriesReached" | "pending">;
+        optional: true;
+    };
+};
+export type JobRecord = InferSchemaType<typeof JobRecordSchema>;

package/dist/types/JobsDefinition.d.ts

@@ -0,0 +1,133 @@
+import { Blackbox, InferSchemaType, SchemaInAnyOrionForm } from '@orion-js/schema';
+import { ScheduleJobOptionsWithoutName, ScheduleJobsResult } from './Events';
+import { ExecutionContext } from './Worker';
+export interface JobRetryResultBase {
+    action: 'retry' | 'dismiss';
+}
+export type JobRetryResultRunIn = JobRetryResultBase & {
+    runIn: number;
+};
+export type JobRetryResultRunAt = JobRetryResultBase & {
+    runAt: Date;
+};
+export type JobRetryResult = JobRetryResultRunIn | JobRetryResultRunAt | JobRetryResultBase;
+export 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;
+}
+export 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>;
+}
+export interface EventJobDefinition<TParamsSchema extends SchemaInAnyOrionForm = any> extends BaseJobDefinition {
+    /**
+     * Type of the job.
+     */
+    type: 'event';
+    /**
+     * Maximum number of tries for this specific event 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;
+    /**
+     * 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>;
+}
+export type CreateEventJobOptions<TParamsSchema extends SchemaInAnyOrionForm = any> = Omit<EventJobDefinition<TParamsSchema>, 'type' | 'schedule' | 'scheduleJobs'>;
+type CreateRecurrentJobBaseOptions = Omit<RecurrentJobDefinition, 'type' | 'runEvery' | 'cron' | 'timezone'>;
+export type CreateRecurrentJobRunEveryOptions = CreateRecurrentJobBaseOptions & {
+    /**
+     * Run every x milliseconds.
+     * Accepts https://github.com/jkroso/parse-duration strings.
+     */
+    runEvery: number | string;
+    cron?: never;
+    timezone?: string;
+};
+export 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;
+};
+export type CreateRecurrentJobOptions = CreateRecurrentJobRunEveryOptions | CreateRecurrentJobCronOptions;
+export type CreateJobOptions<TParamsSchema extends SchemaInAnyOrionForm = any> = CreateEventJobOptions<TParamsSchema> | CreateRecurrentJobOptions;
+export type JobDefinition<TParamsSchema extends SchemaInAnyOrionForm = any> = RecurrentJobDefinition | EventJobDefinition<TParamsSchema>;
+export type JobDefinitionWithName<TParamsSchema extends SchemaInAnyOrionForm = any> = JobDefinition<TParamsSchema> & {
+    name: string;
+};
+export interface JobsDefinition {
+    [jobName: string]: JobDefinition;
+}
+export {};

package/dist/types/StartConfig.d.ts

@@ -0,0 +1,41 @@
+import { JobsDefinition } from './JobsDefinition';
+import { JobToRun } from './Worker';
+export type LogLevels = 'debug' | 'info' | 'warn' | 'error' | 'none';
+export interface StartWorkersConfig {
+    /**
+     * Object map of the jobs that this workers will execute
+     */
+    jobs: JobsDefinition;
+    /**
+     * Maximum number of tries for an event job before it is marked as 'maxTriesReached'.
+     * This is a global default that can be overridden per event job definition.
+     */
+    maxTries?: number;
+    /**
+     * Callback invoked when an event 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;
+}

package/dist/types/Worker.d.ts

@@ -0,0 +1,41 @@
+import { OrionLogger } from '@orion-js/logger';
+import { Blackbox } from '@orion-js/schema';
+import { JobDefinition } from './JobsDefinition';
+export interface JobToRun {
+    jobId: string;
+    executionId: string;
+    name: string;
+    type: 'event' | 'recurrent';
+    params: Blackbox;
+    tries: number;
+    lockTime: number;
+    priority: number;
+    uniqueIdentifier?: string;
+    wasStale?: boolean;
+}
+export interface ExecutionContext {
+    record: JobToRun;
+    definition: JobDefinition;
+    tries: number;
+    logger: OrionLogger;
+    extendLockTime: (extraTime: number) => Promise<void>;
+    clearStaleTimeout: () => void;
+}
+export interface WorkerInstance {
+    running: boolean;
+    workerIndex: number;
+    stop: () => Promise<void>;
+    respawn: () => Promise<void>;
+    promise?: Promise<any>;
+}
+export 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>;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,6 @@
+export * from './Events';
+export * from './HistoryRecord';
+export * from './JobRecord';
+export * from './JobsDefinition';
+export * from './StartConfig';
+export * from './Worker';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orion-js/dogs",
-  "version": "4.3.5",
+  "version": "4.4.0",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -15,37 +15,36 @@
   ],
   "author": "nicolaslopezj",
   "license": "MIT",
-  "scripts": {
-    "test": "bun test",
-    "prepare": "bun run build",
-    "clean": "rm -rf ./dist",
-    "build": "tsup",
-    "dev": "tsup --watch"
-  },
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "@orion-js/helpers": "4.3.1",
-    "@orion-js/schema": "4.3.1",
-    "@orion-js/services": "4.3.1",
-    "@orion-js/typed-model": "4.3.1",
+    "@orion-js/helpers": "4.4.0",
+    "@orion-js/schema": "4.4.0",
+    "@orion-js/services": "4.4.0",
+    "@orion-js/typed-model": "4.4.0",
     "cron-parser": "^5.5.0",
     "dataloader": "2.2.2",
     "dot-object": "^2.1.5",
     "parse-duration": "^2.1.3"
   },
   "peerDependencies": {
-    "@orion-js/logger": "4.3.1",
-    "@orion-js/mongodb": "4.3.1"
+    "@orion-js/logger": "4.4.0",
+    "@orion-js/mongodb": "4.4.0"
   },
   "devDependencies": {
-    "@orion-js/logger": "4.3.1",
-    "@orion-js/mongodb": "4.3.1",
+    "@orion-js/logger": "4.4.0",
+    "@orion-js/mongodb": "4.4.0",
     "mongodb-memory-server": "^10.1.4",
     "tsup": "^8.0.1",
-    "typescript": "^5.4.5"
+    "typescript": "^7.0.2"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "2d14bc085d49a33b2a5566bec1caf60c7d0f897e"
-}
+  "gitHead": "2d14bc085d49a33b2a5566bec1caf60c7d0f897e",
+  "scripts": {
+    "test": "bun test",
+    "clean": "rm -rf ./dist",
+    "build": "tsup && bun run ../../scripts/emit-declarations.ts",
+    "dev": "tsup --watch"
+  }
+}