@neofinancial/chrono 0.4.1-next.0 → 0.5.0

package/README.md

@@ -23,6 +23,16 @@ pnpm add @neofinancial/chrono
 yarn add @neofinancial/chrono
 ```
 
+This package supports both **CommonJS** and **ES Modules**:
+
+```typescript
+// ESM
+import { Chrono } from "@neofinancial/chrono";
+
+// CommonJS
+const { Chrono } = require("@neofinancial/chrono");
+```
+
 ## Basic Usage
 
 ```typescript

package/build/index.d.mts

@@ -0,0 +1,217 @@
+import { EventEmitter } from "node:stream";
+
+//#region src/backoff-strategy.d.ts
+
+interface FixedBackoffStrategyConfig {
+  /** The constant delay in milliseconds. */
+  readonly delayMs: number;
+}
+interface LinearBackoffStrategyConfig {
+  /** The base delay for all retires that will be incremented off of */
+  readonly baseDelayMs?: number;
+  /** The amount to increase the delay by for each subsequent retry in milliseconds. */
+  readonly incrementMs: number;
+}
+interface ExponentialBackoffStrategyConfig {
+  /** The base delay for the first retry (retryAttempt = 0) in milliseconds. */
+  readonly baseDelayMs: number;
+  /** The maximum delay in milliseconds. Defaults to Infinity. */
+  readonly maxDelayMs?: number;
+  /** Type of jitter to apply. Defaults to 'none'. */
+  readonly jitter?: 'none' | 'full' | 'equal';
+}
+type BackoffStrategyOptions = {
+  type: 'none';
+} | ({
+  type: 'fixed';
+} & FixedBackoffStrategyConfig) | ({
+  type: 'linear';
+} & LinearBackoffStrategyConfig) | ({
+  type: 'exponential';
+} & ExponentialBackoffStrategyConfig);
+//#endregion
+//#region src/datastore.d.ts
+declare const TaskStatus: {
+  readonly PENDING: "PENDING";
+  readonly CLAIMED: "CLAIMED";
+  readonly COMPLETED: "COMPLETED";
+  readonly FAILED: "FAILED";
+};
+type TaskStatus = (typeof TaskStatus)[keyof typeof TaskStatus];
+type Task<TaskKind, TaskData> = {
+  /** A unique identifier for the task */
+  id: string;
+  /** A human-readable name or type for the task */
+  kind: TaskKind;
+  /** The current status of the task */
+  status: TaskStatus;
+  /** The payload or data associated with the task */
+  data: TaskData;
+  /** The priority level of the task (lower numbers can indicate higher priority) */
+  priority?: number;
+  /** A key used for idempotency to prevent duplicate processing */
+  idempotencyKey?: string;
+  /** The original scheduled date when the task was first intended to run */
+  originalScheduleDate: Date;
+  /** The current scheduled execution date, which may change if rescheduled */
+  scheduledAt: Date;
+  /** The date the task is mark 'claimed */
+  claimedAt?: Date;
+  /** The date the task is mark 'completed' */
+  completedAt?: Date;
+  /** The date when the task was last executed (if any) */
+  lastExecutedAt?: Date;
+  /** A counter to track the number of times the task has been retried */
+  retryCount: number;
+};
+type ScheduleInput<TaskKind, TaskData, DatastoreOptions> = {
+  when: Date;
+  kind: TaskKind;
+  data: TaskData;
+  priority?: number;
+  idempotencyKey?: string;
+  datastoreOptions?: DatastoreOptions;
+};
+type ClaimTaskInput<TaskKind> = {
+  kind: TaskKind;
+  claimStaleTimeoutMs: number;
+};
+type DeleteByIdempotencyKeyInput<TaskKind> = {
+  kind: TaskKind;
+  idempotencyKey: string;
+};
+type DeleteOptions = {
+  force?: boolean;
+};
+type DeleteInput<TaskKind> = DeleteByIdempotencyKeyInput<TaskKind> | string;
+interface Datastore<TaskMapping extends TaskMappingBase, DatastoreOptions> {
+  schedule<TaskKind extends keyof TaskMapping>(input: ScheduleInput<TaskKind, TaskMapping[TaskKind], DatastoreOptions>): Promise<Task<TaskKind, TaskMapping[TaskKind]>>;
+  delete<TaskKind extends keyof TaskMapping>(taskId: string, options?: DeleteOptions): Promise<Task<TaskKind, TaskMapping[TaskKind]> | undefined>;
+  delete<TaskKind extends keyof TaskMapping>(key: DeleteByIdempotencyKeyInput<TaskKind>, options?: DeleteOptions): Promise<Task<TaskKind, TaskMapping[TaskKind]> | undefined>;
+  claim<TaskKind extends Extract<keyof TaskMapping, string>>(input: ClaimTaskInput<TaskKind>): Promise<Task<TaskKind, TaskMapping[TaskKind]> | undefined>;
+  retry<TaskKind extends keyof TaskMapping>(taskId: string, retryAt: Date): Promise<Task<TaskKind, TaskMapping[TaskKind]>>;
+  complete<TaskKind extends keyof TaskMapping>(taskId: string): Promise<Task<TaskKind, TaskMapping[TaskKind]>>;
+  fail<TaskKind extends keyof TaskMapping>(taskId: string): Promise<Task<TaskKind, TaskMapping[TaskKind]>>;
+}
+//#endregion
+//#region src/events.d.ts
+declare const ChronoEvents: {
+  /** Chrono instance has started processors and begun polling tasks */
+  readonly STARTED: "started";
+  /** Chrono instance has failed to gracefully stop so shutdown has been aborted */
+  readonly STOP_ABORTED: "stopAborted";
+};
+type ChronoEvents = (typeof ChronoEvents)[keyof typeof ChronoEvents];
+type ChronoEventsMap = {
+  [ChronoEvents.STARTED]: [{
+    startedAt: Date;
+  }];
+  [ChronoEvents.STOP_ABORTED]: [{
+    timestamp: Date;
+    error: unknown;
+  }];
+};
+//#endregion
+//#region src/processors/events.d.ts
+declare const ProcessorEvents: {
+  /** A task has been claimed by the running processor for handling */
+  readonly TASK_CLAIMED: "taskClaimed";
+  /** A task has completed processing and successfully marked as completed */
+  readonly TASK_COMPLETED: "taskCompleted";
+  /** A task has failed during processing and being scheduled for retry */
+  readonly TASK_RETRY_SCHEDULED: "taskRetryScheduled";
+  /** A task has been marked as FAILED due to process failures exceeding max retries */
+  readonly TASK_FAILED: "taskFailed";
+  /** A task has been successfully processed but underlying data store failed to mark task as completed. Duplicate processing expected */
+  readonly TASK_COMPLETION_FAILURE: "taskCompletionFailure";
+  /** An unknown and uncaught exception occurred in processor. Processing paused for processLoopRetryIntervalMs before continuing */
+  readonly UNKNOWN_PROCESSING_ERROR: "unknownProcessingError";
+};
+type ProcessorEvents = (typeof ProcessorEvents)[keyof typeof ProcessorEvents];
+type ProcessorEventsMap<TaskKind extends keyof TaskMapping, TaskMapping extends TaskMappingBase> = {
+  [ProcessorEvents.TASK_CLAIMED]: [{
+    task: Task<TaskKind, TaskMapping[TaskKind]>;
+    claimedAt: Date;
+  }];
+  [ProcessorEvents.TASK_COMPLETED]: [{
+    task: Task<TaskKind, TaskMapping[TaskKind]>;
+    completedAt: Date;
+  }];
+  [ProcessorEvents.TASK_RETRY_SCHEDULED]: [{
+    task: Task<TaskKind, TaskMapping[TaskKind]>;
+    error: unknown;
+    retryScheduledAt: Date;
+    errorAt: Date;
+  }];
+  [ProcessorEvents.TASK_FAILED]: [{
+    task: Task<TaskKind, TaskMapping[TaskKind]>;
+    error: unknown;
+    failedAt: Date;
+  }];
+  [ProcessorEvents.TASK_COMPLETION_FAILURE]: [{
+    task: Task<TaskKind, TaskMapping[TaskKind]>;
+    error: unknown;
+    failedAt: Date;
+  }];
+  [ProcessorEvents.UNKNOWN_PROCESSING_ERROR]: [{
+    error: unknown;
+    timestamp: Date;
+  }];
+};
+//#endregion
+//#region src/processors/create-processor.d.ts
+/**
+ * Configuration for the processor.
+ */
+type ProcessorConfiguration = {
+  /** The maximum number of concurrent tasks that the processor will use when processing. @default 1 */
+  maxConcurrency?: number;
+  /** The interval at which the processor will wait before next poll when the previous poll returned a task @default 50ms */
+  claimIntervalMs?: number;
+  /** The interval at which the processor will wait before next poll when no tasks are available for processing @default 5000ms */
+  idleIntervalMs?: number;
+  /** The maximum time a task can be claimed for processing before it will be considered stale and claimed again @default 10000ms */
+  claimStaleTimeoutMs?: number;
+  /** The maximum time a task handler can take to complete before it will be considered timed out @default 5000ms */
+  taskHandlerTimeoutMs?: number;
+  /** The maximum number of retries for a task handler, before task is marked as failed. @default 5 */
+  taskHandlerMaxRetries?: number;
+  /** The interval at which the processor will wait before next poll when an unexpected error occurs @default 20000ms */
+  processLoopRetryIntervalMs?: number;
+};
+//#endregion
+//#region src/chrono.d.ts
+type TaskMappingBase = Record<string, unknown>;
+type ScheduleTaskInput<TaskKind, TaskData, DatastoreOptions> = ScheduleInput<TaskKind, TaskData, DatastoreOptions>;
+type RegisterTaskHandlerInput<TaskKind, TaskData> = {
+  kind: TaskKind;
+  handler: (task: Task<TaskKind, TaskData>) => Promise<void>;
+  backoffStrategyOptions?: BackoffStrategyOptions;
+  processorConfiguration?: ProcessorConfiguration;
+};
+type RegisterTaskHandlerResponse<TaskKind extends keyof TaskMapping, TaskMapping extends TaskMappingBase> = EventEmitter<ProcessorEventsMap<TaskKind, TaskMapping>>;
+/**
+ * This is a type that represents the mapping of task kinds to their respective data types.
+ *
+ * Eg. shape of the TaskMapping type:
+ *
+ * type TaskMapping = {
+ *   "async-messaging": { someField: number };
+ *   "send-email": { url: string };
+ * };
+ *
+ */
+declare class Chrono<TaskMapping extends TaskMappingBase, DatastoreOptions> extends EventEmitter<ChronoEventsMap> {
+  private readonly datastore;
+  private readonly processors;
+  readonly exitTimeoutMs = 60000;
+  constructor(datastore: Datastore<TaskMapping, DatastoreOptions>);
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  scheduleTask<TaskKind extends keyof TaskMapping>(input: ScheduleTaskInput<TaskKind, TaskMapping[TaskKind], DatastoreOptions>): Promise<Task<TaskKind, TaskMapping[TaskKind]>>;
+  deleteTask<TaskKind extends keyof TaskMapping>(taskId: string): Promise<Task<TaskKind, TaskMapping[TaskKind]> | undefined>;
+  registerTaskHandler<TaskKind extends Extract<keyof TaskMapping, string>>(input: RegisterTaskHandlerInput<TaskKind, TaskMapping[TaskKind]>): RegisterTaskHandlerResponse<TaskKind, TaskMapping>;
+}
+//#endregion
+export { Chrono, ChronoEvents, type ClaimTaskInput, type Datastore, type DeleteByIdempotencyKeyInput, type DeleteInput, type DeleteOptions, ProcessorEvents, type ProcessorEventsMap, type RegisterTaskHandlerInput, type RegisterTaskHandlerResponse, type ScheduleInput, type ScheduleTaskInput, type Task, type TaskMappingBase, TaskStatus };
+//# sourceMappingURL=index.d.mts.map

package/build/index.d.ts

@@ -1,4 +1,217 @@
-export { Chrono, type ScheduleTaskInput, type TaskMappingBase, type RegisterTaskHandlerInput, type RegisterTaskHandlerResponse, } from './chrono';
-export { ChronoEvents } from './events';
-export { ProcessorEvents, type ProcessorEventsMap } from './processors';
-export { TaskStatus, type ClaimTaskInput, type Datastore, type ScheduleInput, type Task, type DeleteInput, type DeleteOptions, type DeleteByIdempotencyKeyInput, } from './datastore';
+import { EventEmitter } from "node:stream";
+
+//#region src/backoff-strategy.d.ts
+
+interface FixedBackoffStrategyConfig {
+  /** The constant delay in milliseconds. */
+  readonly delayMs: number;
+}
+interface LinearBackoffStrategyConfig {
+  /** The base delay for all retires that will be incremented off of */
+  readonly baseDelayMs?: number;
+  /** The amount to increase the delay by for each subsequent retry in milliseconds. */
+  readonly incrementMs: number;
+}
+interface ExponentialBackoffStrategyConfig {
+  /** The base delay for the first retry (retryAttempt = 0) in milliseconds. */
+  readonly baseDelayMs: number;
+  /** The maximum delay in milliseconds. Defaults to Infinity. */
+  readonly maxDelayMs?: number;
+  /** Type of jitter to apply. Defaults to 'none'. */
+  readonly jitter?: 'none' | 'full' | 'equal';
+}
+type BackoffStrategyOptions = {
+  type: 'none';
+} | ({
+  type: 'fixed';
+} & FixedBackoffStrategyConfig) | ({
+  type: 'linear';
+} & LinearBackoffStrategyConfig) | ({
+  type: 'exponential';
+} & ExponentialBackoffStrategyConfig);
+//#endregion
+//#region src/datastore.d.ts
+declare const TaskStatus: {
+  readonly PENDING: "PENDING";
+  readonly CLAIMED: "CLAIMED";
+  readonly COMPLETED: "COMPLETED";
+  readonly FAILED: "FAILED";
+};
+type TaskStatus = (typeof TaskStatus)[keyof typeof TaskStatus];
+type Task<TaskKind, TaskData> = {
+  /** A unique identifier for the task */
+  id: string;
+  /** A human-readable name or type for the task */
+  kind: TaskKind;
+  /** The current status of the task */
+  status: TaskStatus;
+  /** The payload or data associated with the task */
+  data: TaskData;
+  /** The priority level of the task (lower numbers can indicate higher priority) */
+  priority?: number;
+  /** A key used for idempotency to prevent duplicate processing */
+  idempotencyKey?: string;
+  /** The original scheduled date when the task was first intended to run */
+  originalScheduleDate: Date;
+  /** The current scheduled execution date, which may change if rescheduled */
+  scheduledAt: Date;
+  /** The date the task is mark 'claimed */
+  claimedAt?: Date;
+  /** The date the task is mark 'completed' */
+  completedAt?: Date;
+  /** The date when the task was last executed (if any) */
+  lastExecutedAt?: Date;
+  /** A counter to track the number of times the task has been retried */
+  retryCount: number;
+};
+type ScheduleInput<TaskKind, TaskData, DatastoreOptions> = {
+  when: Date;
+  kind: TaskKind;
+  data: TaskData;
+  priority?: number;
+  idempotencyKey?: string;
+  datastoreOptions?: DatastoreOptions;
+};
+type ClaimTaskInput<TaskKind> = {
+  kind: TaskKind;
+  claimStaleTimeoutMs: number;
+};
+type DeleteByIdempotencyKeyInput<TaskKind> = {
+  kind: TaskKind;
+  idempotencyKey: string;
+};
+type DeleteOptions = {
+  force?: boolean;
+};
+type DeleteInput<TaskKind> = DeleteByIdempotencyKeyInput<TaskKind> | string;
+interface Datastore<TaskMapping extends TaskMappingBase, DatastoreOptions> {
+  schedule<TaskKind extends keyof TaskMapping>(input: ScheduleInput<TaskKind, TaskMapping[TaskKind], DatastoreOptions>): Promise<Task<TaskKind, TaskMapping[TaskKind]>>;
+  delete<TaskKind extends keyof TaskMapping>(taskId: string, options?: DeleteOptions): Promise<Task<TaskKind, TaskMapping[TaskKind]> | undefined>;
+  delete<TaskKind extends keyof TaskMapping>(key: DeleteByIdempotencyKeyInput<TaskKind>, options?: DeleteOptions): Promise<Task<TaskKind, TaskMapping[TaskKind]> | undefined>;
+  claim<TaskKind extends Extract<keyof TaskMapping, string>>(input: ClaimTaskInput<TaskKind>): Promise<Task<TaskKind, TaskMapping[TaskKind]> | undefined>;
+  retry<TaskKind extends keyof TaskMapping>(taskId: string, retryAt: Date): Promise<Task<TaskKind, TaskMapping[TaskKind]>>;
+  complete<TaskKind extends keyof TaskMapping>(taskId: string): Promise<Task<TaskKind, TaskMapping[TaskKind]>>;
+  fail<TaskKind extends keyof TaskMapping>(taskId: string): Promise<Task<TaskKind, TaskMapping[TaskKind]>>;
+}
+//#endregion
+//#region src/events.d.ts
+declare const ChronoEvents: {
+  /** Chrono instance has started processors and begun polling tasks */
+  readonly STARTED: "started";
+  /** Chrono instance has failed to gracefully stop so shutdown has been aborted */
+  readonly STOP_ABORTED: "stopAborted";
+};
+type ChronoEvents = (typeof ChronoEvents)[keyof typeof ChronoEvents];
+type ChronoEventsMap = {
+  [ChronoEvents.STARTED]: [{
+    startedAt: Date;
+  }];
+  [ChronoEvents.STOP_ABORTED]: [{
+    timestamp: Date;
+    error: unknown;
+  }];
+};
+//#endregion
+//#region src/processors/events.d.ts
+declare const ProcessorEvents: {
+  /** A task has been claimed by the running processor for handling */
+  readonly TASK_CLAIMED: "taskClaimed";
+  /** A task has completed processing and successfully marked as completed */
+  readonly TASK_COMPLETED: "taskCompleted";
+  /** A task has failed during processing and being scheduled for retry */
+  readonly TASK_RETRY_SCHEDULED: "taskRetryScheduled";
+  /** A task has been marked as FAILED due to process failures exceeding max retries */
+  readonly TASK_FAILED: "taskFailed";
+  /** A task has been successfully processed but underlying data store failed to mark task as completed. Duplicate processing expected */
+  readonly TASK_COMPLETION_FAILURE: "taskCompletionFailure";
+  /** An unknown and uncaught exception occurred in processor. Processing paused for processLoopRetryIntervalMs before continuing */
+  readonly UNKNOWN_PROCESSING_ERROR: "unknownProcessingError";
+};
+type ProcessorEvents = (typeof ProcessorEvents)[keyof typeof ProcessorEvents];
+type ProcessorEventsMap<TaskKind extends keyof TaskMapping, TaskMapping extends TaskMappingBase> = {
+  [ProcessorEvents.TASK_CLAIMED]: [{
+    task: Task<TaskKind, TaskMapping[TaskKind]>;
+    claimedAt: Date;
+  }];
+  [ProcessorEvents.TASK_COMPLETED]: [{
+    task: Task<TaskKind, TaskMapping[TaskKind]>;
+    completedAt: Date;
+  }];
+  [ProcessorEvents.TASK_RETRY_SCHEDULED]: [{
+    task: Task<TaskKind, TaskMapping[TaskKind]>;
+    error: unknown;
+    retryScheduledAt: Date;
+    errorAt: Date;
+  }];
+  [ProcessorEvents.TASK_FAILED]: [{
+    task: Task<TaskKind, TaskMapping[TaskKind]>;
+    error: unknown;
+    failedAt: Date;
+  }];
+  [ProcessorEvents.TASK_COMPLETION_FAILURE]: [{
+    task: Task<TaskKind, TaskMapping[TaskKind]>;
+    error: unknown;
+    failedAt: Date;
+  }];
+  [ProcessorEvents.UNKNOWN_PROCESSING_ERROR]: [{
+    error: unknown;
+    timestamp: Date;
+  }];
+};
+//#endregion
+//#region src/processors/create-processor.d.ts
+/**
+ * Configuration for the processor.
+ */
+type ProcessorConfiguration = {
+  /** The maximum number of concurrent tasks that the processor will use when processing. @default 1 */
+  maxConcurrency?: number;
+  /** The interval at which the processor will wait before next poll when the previous poll returned a task @default 50ms */
+  claimIntervalMs?: number;
+  /** The interval at which the processor will wait before next poll when no tasks are available for processing @default 5000ms */
+  idleIntervalMs?: number;
+  /** The maximum time a task can be claimed for processing before it will be considered stale and claimed again @default 10000ms */
+  claimStaleTimeoutMs?: number;
+  /** The maximum time a task handler can take to complete before it will be considered timed out @default 5000ms */
+  taskHandlerTimeoutMs?: number;
+  /** The maximum number of retries for a task handler, before task is marked as failed. @default 5 */
+  taskHandlerMaxRetries?: number;
+  /** The interval at which the processor will wait before next poll when an unexpected error occurs @default 20000ms */
+  processLoopRetryIntervalMs?: number;
+};
+//#endregion
+//#region src/chrono.d.ts
+type TaskMappingBase = Record<string, unknown>;
+type ScheduleTaskInput<TaskKind, TaskData, DatastoreOptions> = ScheduleInput<TaskKind, TaskData, DatastoreOptions>;
+type RegisterTaskHandlerInput<TaskKind, TaskData> = {
+  kind: TaskKind;
+  handler: (task: Task<TaskKind, TaskData>) => Promise<void>;
+  backoffStrategyOptions?: BackoffStrategyOptions;
+  processorConfiguration?: ProcessorConfiguration;
+};
+type RegisterTaskHandlerResponse<TaskKind extends keyof TaskMapping, TaskMapping extends TaskMappingBase> = EventEmitter<ProcessorEventsMap<TaskKind, TaskMapping>>;
+/**
+ * This is a type that represents the mapping of task kinds to their respective data types.
+ *
+ * Eg. shape of the TaskMapping type:
+ *
+ * type TaskMapping = {
+ *   "async-messaging": { someField: number };
+ *   "send-email": { url: string };
+ * };
+ *
+ */
+declare class Chrono<TaskMapping extends TaskMappingBase, DatastoreOptions> extends EventEmitter<ChronoEventsMap> {
+  private readonly datastore;
+  private readonly processors;
+  readonly exitTimeoutMs = 60000;
+  constructor(datastore: Datastore<TaskMapping, DatastoreOptions>);
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  scheduleTask<TaskKind extends keyof TaskMapping>(input: ScheduleTaskInput<TaskKind, TaskMapping[TaskKind], DatastoreOptions>): Promise<Task<TaskKind, TaskMapping[TaskKind]>>;
+  deleteTask<TaskKind extends keyof TaskMapping>(taskId: string): Promise<Task<TaskKind, TaskMapping[TaskKind]> | undefined>;
+  registerTaskHandler<TaskKind extends Extract<keyof TaskMapping, string>>(input: RegisterTaskHandlerInput<TaskKind, TaskMapping[TaskKind]>): RegisterTaskHandlerResponse<TaskKind, TaskMapping>;
+}
+//#endregion
+export { Chrono, ChronoEvents, type ClaimTaskInput, type Datastore, type DeleteByIdempotencyKeyInput, type DeleteInput, type DeleteOptions, ProcessorEvents, type ProcessorEventsMap, type RegisterTaskHandlerInput, type RegisterTaskHandlerResponse, type ScheduleInput, type ScheduleTaskInput, type Task, type TaskMappingBase, TaskStatus };
+//# sourceMappingURL=index.d.ts.map