@decaf-ts/core 0.18.0 → 0.20.0

package/lib/types/tasks/TaskEngine.d.cts

@@ -0,0 +1,97 @@
+import { TaskModel } from "./models/TaskModel.cjs";
+import { Repo } from "../repository/Repository.cjs";
+import { TaskEventModel } from "./models/TaskEventModel.cjs";
+import { TaskHandlerRegistry } from "./TaskHandlerRegistry.cjs";
+import { TaskEventBus } from "./TaskEventBus.cjs";
+import { TaskStepResultModel } from "./models/TaskStepResultModel.cjs";
+import { TaskLogEntryModel } from "./models/TaskLogEntryModel.cjs";
+import { TaskBackoffModel } from "./models/TaskBackoffModel.cjs";
+import { TaskStepSpecModel } from "./models/TaskStepSpecModel.cjs";
+import { TaskEventType, TaskStatus } from "./constants.cjs";
+import { Adapter } from "../persistence/Adapter.cjs";
+import { Context } from "../persistence/Context.cjs";
+import { ContextOf, FlagsOf } from "../persistence/types.cjs";
+import { LogLevel } from "@decaf-ts/logging";
+import { AbsContextual, ContextualArgs, MaybeContextualArg } from "../utils/ContextualLoggedClass.cjs";
+import { OperationKeys } from "@decaf-ts/db-decorators";
+import { TaskContext } from "./TaskContext.cjs";
+import { TaskStateChangeRequest } from "./TaskStateChangeError.cjs";
+import { DateTarget } from "@decaf-ts/decorator-validation";
+import { Constructor } from "@decaf-ts/decoration";
+import { TaskEngineConfig, TaskFlags } from "./types.cjs";
+import { TaskTracker } from "./TaskTracker.cjs";
+import { Lock } from "@decaf-ts/transactional-decorators";
+type ParsedTaskDependency = {
+    taskId: string;
+    stepRef?: string;
+};
+export declare class TaskEngine<A extends Adapter<any, any, any, any>, C extends TaskEngineConfig<A> = TaskEngineConfig<A>> extends AbsContextual<ContextOf<A>> {
+    protected config: C;
+    private _tasks?;
+    private _events?;
+    private _adapter?;
+    protected lock: Lock;
+    protected get Context(): Constructor<ContextOf<A>>;
+    protected get adapter(): A;
+    protected get registry(): TaskHandlerRegistry;
+    protected get bus(): TaskEventBus;
+    protected get tasks(): Repo<TaskModel>;
+    protected get events(): Repo<TaskEventModel>;
+    protected running: boolean;
+    private idleDelayMs;
+    static createTaskContext(base?: Context<any>, overrides?: Partial<TaskFlags>): TaskContext;
+    constructor(config: C);
+    push<I, O>(task: TaskModel<I, O>, ...args: MaybeContextualArg<any>): Promise<TaskModel<I, O>>;
+    push<I, O>(task: TaskModel<I, O>, track: false, ...args: MaybeContextualArg<any>): Promise<TaskModel<I, O>>;
+    push<I, O>(task: TaskModel<I, O>, track: true, ...args: MaybeContextualArg<any>): Promise<{
+        task: TaskModel<I, O>;
+        tracker: TaskTracker<(typeof task)["output"]>;
+    }>;
+    schedule<I, O>(task: TaskModel<I, O>, ...args: MaybeContextualArg<any>): {
+        for: (when: DateTarget) => Promise<TaskModel<I, O>>;
+    };
+    schedule<I, O>(task: TaskModel<I, O>, track: false, ...args: MaybeContextualArg<any>): {
+        for: (when: DateTarget) => Promise<TaskModel<I, O>>;
+    };
+    schedule<I, O>(task: TaskModel<I, O>, track: true, ...args: MaybeContextualArg<any>): {
+        for: (when: DateTarget) => Promise<{
+            task: TaskModel<I, O>;
+            tracker: TaskTracker<O>;
+        }>;
+    };
+    track(id: string, ...args: MaybeContextualArg<any>): Promise<{
+        task: TaskModel<any, any>;
+        tracker: TaskTracker<any>;
+    }>;
+    protected ensureTaskError(task: TaskModel, ctx: Context): Promise<TaskModel>;
+    cancel(id: string, ...args: MaybeContextualArg<any>): Promise<TaskModel>;
+    isRunning(): Promise<boolean>;
+    start(...args: MaybeContextualArg<any>): Promise<void>;
+    stop(...args: MaybeContextualArg<any>): Promise<void>;
+    protected loop(...args: ContextualArgs<any>): Promise<void>;
+    protected claimBatch(ctx: Context<any>): Promise<TaskModel[]>;
+    protected tryClaim(task: TaskModel, ctx: Context): Promise<TaskModel | null>;
+    protected isTaskFinished(status?: TaskStatus): boolean;
+    protected parseTaskDependency(value: string): ParsedTaskDependency | undefined;
+    protected normalizeDependencies(deps: string[] | string | undefined): ParsedTaskDependency[];
+    protected resolveDependencyStepIndex(task: TaskModel, stepRef: string): number | undefined;
+    protected areDependenciesSatisfied(dependencies: ParsedTaskDependency[], ctx: Context): Promise<boolean>;
+    protected getStepLock(task: TaskModel, stepIndex: number | undefined): string | undefined;
+    protected hasLockConflict(task: TaskModel, stepIndex: number | undefined, ctx: Context): Promise<boolean>;
+    protected isRunnable(task: TaskModel, ctx: Context): Promise<boolean>;
+    protected executeClaimed(task: TaskModel): Promise<void>;
+    protected handleTaskStateChange(request: TaskStateChangeRequest, task: TaskModel, ctx: TaskContext): Promise<void>;
+    protected runComposite(task: TaskModel, context: TaskContext): Promise<any>;
+    protected normalizeBackoff(backoff: TaskBackoffModel | string | object | any): TaskBackoffModel;
+    protected normalizeSteps(steps: TaskStepSpecModel[] | string | undefined): TaskStepSpecModel[];
+    protected normalizeStepResults(results: TaskStepResultModel[] | string | undefined): TaskStepResultModel[];
+    protected appendLog(ctx: TaskContext | Context, task: TaskModel, logEntries: [LogLevel, string] | [LogLevel, string, any] | ([LogLevel, string] | [LogLevel, string, any])[]): Promise<[TaskModel, TaskLogEntryModel[]]>;
+    protected emitStatus(ctx: TaskContext | Context, task: TaskModel, status: TaskStatus, outputOrError?: any | Error, originalError?: Error): Promise<void>;
+    protected emitLog(ctx: TaskContext | Context, taskId: string, entries: TaskLogEntryModel[]): Promise<void>;
+    protected normalizePipeArgs(args: any[]): ([LogLevel, string] | [LogLevel, string, any])[];
+    protected emitProgress(ctx: TaskContext | Context, taskId: string, data: any): Promise<void>;
+    protected persistEvent(ctx: TaskContext | Context, taskId: string, type: TaskEventType, payload: any): Promise<TaskEventModel>;
+    toString(): string;
+    context(operation: ((...args: any[]) => any) | OperationKeys.CREATE | OperationKeys.READ | OperationKeys.UPDATE | OperationKeys.DELETE | string, overrides: Partial<FlagsOf<ContextOf<A>>>, ...args: any[]): Promise<ContextOf<A>>;
+}
+export {};

package/lib/types/tasks/{TaskEngine.d.ts → TaskEngine.d.mts}

@@ -1,25 +1,25 @@
-import { TaskModel } from "./models/TaskModel";
-import { Repo } from "../repository/Repository";
-import { TaskEventModel } from "./models/TaskEventModel";
-import { TaskHandlerRegistry } from "./TaskHandlerRegistry";
-import { TaskEventBus } from "./TaskEventBus";
-import { TaskStepResultModel } from "./models/TaskStepResultModel";
-import { TaskLogEntryModel } from "./models/TaskLogEntryModel";
-import { TaskBackoffModel } from "./models/TaskBackoffModel";
-import { TaskStepSpecModel } from "./models/TaskStepSpecModel";
-import { TaskEventType, TaskStatus } from "./constants";
-import { Adapter } from "../persistence/Adapter";
-import { Context } from "../persistence/Context";
-import { ContextOf, FlagsOf } from "../persistence/types";
+import { TaskModel } from "./models/TaskModel.js";
+import { Repo } from "../repository/Repository.js";
+import { TaskEventModel } from "./models/TaskEventModel.js";
+import { TaskHandlerRegistry } from "./TaskHandlerRegistry.js";
+import { TaskEventBus } from "./TaskEventBus.js";
+import { TaskStepResultModel } from "./models/TaskStepResultModel.js";
+import { TaskLogEntryModel } from "./models/TaskLogEntryModel.js";
+import { TaskBackoffModel } from "./models/TaskBackoffModel.js";
+import { TaskStepSpecModel } from "./models/TaskStepSpecModel.js";
+import { TaskEventType, TaskStatus } from "./constants.js";
+import { Adapter } from "../persistence/Adapter.js";
+import { Context } from "../persistence/Context.js";
+import { ContextOf, FlagsOf } from "../persistence/types.js";
 import { LogLevel } from "@decaf-ts/logging";
-import { AbsContextual, ContextualArgs, MaybeContextualArg } from "../utils/ContextualLoggedClass";
+import { AbsContextual, ContextualArgs, MaybeContextualArg } from "../utils/ContextualLoggedClass.js";
 import { OperationKeys } from "@decaf-ts/db-decorators";
-import { TaskContext } from "./TaskContext";
-import { TaskStateChangeRequest } from "./TaskStateChangeError";
+import { TaskContext } from "./TaskContext.js";
+import { TaskStateChangeRequest } from "./TaskStateChangeError.js";
 import { DateTarget } from "@decaf-ts/decorator-validation";
 import { Constructor } from "@decaf-ts/decoration";
-import { TaskEngineConfig, TaskFlags } from "./types";
-import { TaskTracker } from "./TaskTracker";
+import { TaskEngineConfig, TaskFlags } from "./types.js";
+import { TaskTracker } from "./TaskTracker.js";
 import { Lock } from "@decaf-ts/transactional-decorators";
 type ParsedTaskDependency = {
     taskId: string;

package/lib/types/tasks/TaskErrors.d.cts

@@ -0,0 +1,65 @@
+import { BaseError } from "@decaf-ts/db-decorators";
+import { TaskErrorModel } from "./models/TaskErrorModel.cjs";
+import { TaskStatus } from "./constants.cjs";
+/**
+ * Represents the next action to take after a task error.
+ * Used to identify the appropriate response to task failures.
+ */
+export type TaskNextAction = TaskStatus.CANCELED | TaskStatus.WAITING_RETRY | TaskStatus.SCHEDULED | TaskStatus.FAILED;
+/**
+ * Additional properties added to errors from TaskTracker.resolve() and TaskTracker.wait()
+ */
+export type TaskErrorProps = {
+    /** The next action to take in response to this error */
+    nextAction: TaskNextAction;
+    /** The task ID this error relates to (optional, present on TaskControlError) */
+    taskId?: string;
+    /** Additional error details (optional, present on TaskControlError) */
+    details?: TaskErrorModel;
+    /** Additional metadata (optional, present on TaskControlError) */
+    meta?: Record<string, any>;
+};
+/**
+ * Generic type that preserves the original error type while adding task-specific properties.
+ * Use this to type errors from TaskTracker.resolve() and TaskTracker.wait().
+ *
+ * The original error is preserved (e.g., ValidationError stays ValidationError),
+ * with the nextAction property added to identify the appropriate response:
+ * - `TaskStatus.CANCELED`: Task was explicitly canceled
+ * - `TaskStatus.SCHEDULED`: Task was rescheduled
+ * - `TaskStatus.WAITING_RETRY`: Task is waiting for retry
+ * - `TaskStatus.FAILED`: Task has permanently failed
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await tracker.resolve();
+ * } catch (error: unknown) {
+ *   if (isTaskError<ValidationError>(error, ValidationError)) {
+ *     // error is typed as TaskErrorFrom<ValidationError>
+ *     console.log(error.nextAction); // TaskNextAction
+ *     console.log(error.code);       // ValidationError's code property
+ *   }
+ * }
+ * ```
+ */
+export type TaskErrorFrom<E extends Error> = E & TaskErrorProps;
+export declare function isTaskError<E extends Error = Error>(error: unknown, ErrorClass?: new (...args: any[]) => E): error is TaskErrorFrom<E>;
+export declare class TaskControlError extends BaseError {
+    readonly taskId: string;
+    readonly details?: TaskErrorModel;
+    readonly meta?: Record<string, any>;
+    constructor(name: string, taskId: string, message: string, details?: TaskErrorModel, meta?: Record<string, any>, code?: number);
+}
+export declare class TaskFailError extends TaskControlError {
+    constructor(taskId: string, details?: TaskErrorModel, meta?: Record<string, any>);
+}
+export declare class TaskRetryError extends TaskControlError {
+    constructor(taskId: string, details?: TaskErrorModel, meta?: Record<string, any>);
+}
+export declare class TaskCancelError extends TaskControlError {
+    constructor(taskId: string, details?: TaskErrorModel, meta?: Record<string, any>);
+}
+export declare class TaskRescheduleError extends TaskControlError {
+    constructor(taskId: string, details?: TaskErrorModel, meta?: Record<string, any>);
+}

package/lib/types/tasks/{TaskErrors.d.ts → TaskErrors.d.mts}

@@ -1,6 +1,6 @@
 import { BaseError } from "@decaf-ts/db-decorators";
-import { TaskErrorModel } from "./models/TaskErrorModel";
-import { TaskStatus } from "./constants";
+import { TaskErrorModel } from "./models/TaskErrorModel.js";
+import { TaskStatus } from "./constants.js";
 /**
  * Represents the next action to take after a task error.
  * Used to identify the appropriate response to task failures.

package/lib/types/tasks/TaskEventBus.d.cts

@@ -0,0 +1,17 @@
+import { TaskEventModel } from "./models/TaskEventModel.cjs";
+import { Context } from "../persistence/Context.cjs";
+import { ObserverHandler } from "../persistence/ObserverHandler.cjs";
+import { EventIds, ObserverFilter } from "../persistence/types.cjs";
+import { TaskContext } from "./TaskContext.cjs";
+import { Observer } from "../interfaces/Observer.cjs";
+import { Constructor } from "@decaf-ts/decoration";
+import { BulkCrudOperationKeys, OperationKeys } from "@decaf-ts/db-decorators";
+import { ContextualArgs } from "../utils/index.cjs";
+import { Model } from "@decaf-ts/decorator-validation";
+export declare class TaskEventBus extends ObserverHandler<TaskContext> {
+    protected readonly listeners: Set<(evt: TaskEventModel) => void>;
+    observe(observer: Observer, filter?: ObserverFilter): () => void;
+    unObserve(observer: Observer): void;
+    emit(evt: TaskEventModel, ctx: Context): void;
+    updateObservers<M extends Model>(model: Constructor<M> | string, event: OperationKeys | BulkCrudOperationKeys | string, id: EventIds, evt: TaskEventModel, ...args: ContextualArgs<any>): Promise<void>;
+}

package/lib/types/tasks/{TaskEventBus.d.ts → TaskEventBus.d.mts}

@@ -1,12 +1,12 @@
-import { TaskEventModel } from "./models/TaskEventModel";
-import { Context } from "../persistence/Context";
-import { ObserverHandler } from "../persistence/ObserverHandler";
-import { EventIds, ObserverFilter } from "../persistence/types";
-import { TaskContext } from "./TaskContext";
-import { Observer } from "../interfaces/Observer";
+import { TaskEventModel } from "./models/TaskEventModel.js";
+import { Context } from "../persistence/Context.js";
+import { ObserverHandler } from "../persistence/ObserverHandler.js";
+import { EventIds, ObserverFilter } from "../persistence/types.js";
+import { TaskContext } from "./TaskContext.js";
+import { Observer } from "../interfaces/Observer.js";
 import { Constructor } from "@decaf-ts/decoration";
 import { BulkCrudOperationKeys, OperationKeys } from "@decaf-ts/db-decorators";
-import { ContextualArgs } from "../utils/index";
+import { ContextualArgs } from "../utils/index.js";
 import { Model } from "@decaf-ts/decorator-validation";
 export declare class TaskEventBus extends ObserverHandler<TaskContext> {
     protected readonly listeners: Set<(evt: TaskEventModel) => void>;

package/lib/types/tasks/TaskEventService.d.cts

@@ -0,0 +1,7 @@
+import { type Repo } from "../repository/Repository.cjs";
+import { ModelService } from "../services/ModelService.cjs";
+import { TaskEventModel } from "./models/TaskEventModel.cjs";
+export declare class TaskEventService extends ModelService<TaskEventModel> {
+    constructor();
+    get repo(): Repo<TaskEventModel>;
+}

package/lib/types/tasks/TaskEventService.d.mts

@@ -0,0 +1,7 @@
+import { type Repo } from "../repository/Repository.js";
+import { ModelService } from "../services/ModelService.js";
+import { TaskEventModel } from "./models/TaskEventModel.js";
+export declare class TaskEventService extends ModelService<TaskEventModel> {
+    constructor();
+    get repo(): Repo<TaskEventModel>;
+}

package/lib/types/tasks/TaskHandler.d.cts

@@ -0,0 +1,12 @@
+import { ITaskHandler } from "./types.cjs";
+import { AbsContextual, ContextualArgs } from "../utils/ContextualLoggedClass.cjs";
+import { TaskContext } from "./TaskContext.cjs";
+export declare abstract class TaskHandler<I, O> extends AbsContextual<TaskContext> implements ITaskHandler<I, O> {
+    private _type?;
+    get type(): string;
+    protected constructor();
+    protected runPrefix(input: I, ...args: ContextualArgs<TaskContext>): Promise<any[]>;
+    protected runSuffix(output: O, ctx: TaskContext): O;
+    catch(input: I, error: unknown, ctx: TaskContext): Promise<void>;
+    abstract run(input: I, ctx: TaskContext): Promise<O>;
+}

package/lib/types/tasks/{TaskHandler.d.ts → TaskHandler.d.mts}

@@ -1,6 +1,6 @@
-import { ITaskHandler } from "./types";
-import { AbsContextual, ContextualArgs } from "../utils/ContextualLoggedClass";
-import { TaskContext } from "./TaskContext";
+import { ITaskHandler } from "./types.js";
+import { AbsContextual, ContextualArgs } from "../utils/ContextualLoggedClass.js";
+import { TaskContext } from "./TaskContext.js";
 export declare abstract class TaskHandler<I, O> extends AbsContextual<TaskContext> implements ITaskHandler<I, O> {
     private _type?;
     get type(): string;

package/lib/types/tasks/TaskHandlerRegistry.d.cts

@@ -0,0 +1,8 @@
+import { ITaskHandler } from "./types.cjs";
+export declare class TaskHandlerRegistry {
+    private readonly handlers;
+    constructor();
+    protected initialize(): void;
+    register(handler: ITaskHandler): void;
+    get(type: string): ITaskHandler | undefined;
+}

package/lib/types/tasks/{TaskHandlerRegistry.d.ts → TaskHandlerRegistry.d.mts}

@@ -1,4 +1,4 @@
-import { ITaskHandler } from "./types";
+import { ITaskHandler } from "./types.js";
 export declare class TaskHandlerRegistry {
     private readonly handlers;
     constructor();

package/lib/types/tasks/TaskService.d.cts

@@ -0,0 +1,65 @@
+import { type ContextualArgs, type ContextualizedArgs, type MaybeContextualArg, type MethodOrOperation } from "../utils/ContextualLoggedClass.cjs";
+import { ClientBasedService } from "../services/services.cjs";
+import { TaskEngine } from "./TaskEngine.cjs";
+import { Adapter } from "../persistence/Adapter.cjs";
+import { type AllOperationKeys, type ContextOf, type EventIds, type ObserverFilter } from "../persistence/types.cjs";
+import { type PrimaryKeyType } from "@decaf-ts/db-decorators";
+import { OrderDirection } from "../repository/constants.cjs";
+import { type Repo } from "../repository/Repository.cjs";
+import { TaskModel } from "./models/TaskModel.cjs";
+import { type DirectionLimitOffset } from "../query/types.cjs";
+import type { Constructor } from "@decaf-ts/decoration";
+import type { Observer } from "../interfaces/Observer.cjs";
+import type { ArrayMode } from "../services/ModelService.cjs";
+import { TaskEngineConfig } from "./types.cjs";
+import { TaskTracker } from "./TaskTracker.cjs";
+import { TaskEventModel } from "./models/index.cjs";
+import { SelectSelector, WhereOption } from "../query/index.cjs";
+export type TaskServiceConfig<A extends Adapter<any, any, any, any>, T extends TaskEngine<A> = TaskEngine<A>, C extends TaskEngineConfig<A> = TaskEngineConfig<A>> = C & {
+    engine?: Constructor<T>;
+};
+export declare class TaskService<A extends Adapter<any, any, any, any>> extends ClientBasedService<TaskEngine<A>, TaskEngineConfig<A>> {
+    protected get adapter(): A;
+    protected get tasks(): Repo<TaskModel>;
+    protected get events(): Repo<TaskEventModel>;
+    constructor();
+    initialize(...args: MaybeContextualArg<ContextOf<A>>): Promise<{
+        config: TaskServiceConfig<A, any, any>;
+        client: TaskEngine<A>;
+    }>;
+    push<I, O>(task: TaskModel<I, O>, ...args: MaybeContextualArg<any>): Promise<TaskModel<I, O>>;
+    push<I, O>(task: TaskModel<I, O>, track: false, ...args: MaybeContextualArg<any>): Promise<TaskModel<I, O>>;
+    push<I, O>(task: TaskModel<I, O>, track: true, ...args: MaybeContextualArg<any>): Promise<{
+        task: TaskModel<I, O>;
+        tracker: TaskTracker<O>;
+    }>;
+    track(id: string, ...args: MaybeContextualArg<any>): Promise<{
+        task: TaskModel;
+        tracker: TaskTracker<any>;
+    }>;
+    select<S extends readonly SelectSelector<TaskModel>[]>(): WhereOption<TaskModel, TaskModel[]>;
+    select<S extends readonly SelectSelector<TaskModel>[]>(selector: readonly [...S]): WhereOption<TaskModel, Pick<TaskModel, S[number]>[]>;
+    create(model: TaskModel, ...args: MaybeContextualArg<ContextOf<A>>): Promise<TaskModel>;
+    createAll(models: TaskModel[], ...args: MaybeContextualArg<ContextOf<A>>): Promise<TaskModel[]>;
+    delete(key: PrimaryKeyType, ...args: MaybeContextualArg<ContextOf<A>>): Promise<TaskModel>;
+    deleteAll(keys: PrimaryKeyType[], ...args: MaybeContextualArg<ContextOf<A>>): Promise<TaskModel[]>;
+    read(key: PrimaryKeyType, ...args: MaybeContextualArg<ContextOf<A>>): Promise<TaskModel>;
+    readAll(keys: PrimaryKeyType[], ...args: MaybeContextualArg<ContextOf<A>>): Promise<TaskModel[]>;
+    query<M, R extends ArrayMode = "one">(methodName: string, ...args: MaybeContextualArg<ContextOf<A>>): Promise<R extends "one" ? M : M[]>;
+    update(model: TaskModel, ...args: MaybeContextualArg<ContextOf<A>>): Promise<TaskModel>;
+    updateAll(models: TaskModel[], ...args: MaybeContextualArg<ContextOf<A>>): Promise<TaskModel[]>;
+    listBy(key: keyof TaskModel, order: OrderDirection, ...args: MaybeContextualArg<ContextOf<A>>): Promise<TaskModel<any, any>[]>;
+    paginateBy(key: keyof TaskModel, order: OrderDirection, ref: Omit<DirectionLimitOffset, "direction">, ...args: MaybeContextualArg<ContextOf<A>>): Promise<import("..").SerializedPage<TaskModel<any, any>>>;
+    findOneBy(key: keyof TaskModel, value: any, ...args: MaybeContextualArg<ContextOf<A>>): Promise<TaskModel<any, any>>;
+    findBy(key: keyof TaskModel, value: any, ...args: MaybeContextualArg<ContextOf<A>>): Promise<TaskModel<any, any>[]>;
+    findByPaginate(key: keyof TaskModel, value: any, ref: DirectionLimitOffset, ...args: MaybeContextualArg<ContextOf<A>>): Promise<import("..").SerializedPage<TaskModel<any, any>>>;
+    statement(name: string, ...args: MaybeContextualArg<ContextOf<A>>): Promise<any>;
+    refresh(table: Constructor<any>, event: AllOperationKeys, id: EventIds, ...args: ContextualArgs<ContextOf<A>>): Promise<void>;
+    observe(observer: Observer, filter?: ObserverFilter): () => void;
+    unObserve(observer: Observer): void;
+    updateObservers(model: Constructor, operation: AllOperationKeys, ids: EventIds, ...args: ContextualArgs<ContextOf<A>>): Promise<void>;
+    protected logCtx<ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<ContextOf<A>, ARGS>, operation: METHOD): ContextualizedArgs<ContextOf<A>, ARGS, METHOD extends string ? true : false>;
+    protected logCtx<ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<ContextOf<A>, ARGS>, operation: METHOD, allowCreate: false): ContextualizedArgs<ContextOf<A>, ARGS, METHOD extends string ? true : false>;
+    protected logCtx<ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<ContextOf<A>, ARGS>, operation: METHOD, allowCreate: true): Promise<ContextualizedArgs<ContextOf<A>, ARGS, METHOD extends string ? true : false>>;
+    shutdown(...args: MaybeContextualArg<any>): Promise<void>;
+}

package/lib/types/tasks/{TaskService.d.ts → TaskService.d.mts}

@@ -1,20 +1,20 @@
-import { type ContextualArgs, type ContextualizedArgs, type MaybeContextualArg, type MethodOrOperation } from "../utils/ContextualLoggedClass";
-import { ClientBasedService } from "../services/services";
-import { TaskEngine } from "./TaskEngine";
-import { Adapter } from "../persistence/Adapter";
-import { type AllOperationKeys, type ContextOf, type EventIds, type ObserverFilter } from "../persistence/types";
+import { type ContextualArgs, type ContextualizedArgs, type MaybeContextualArg, type MethodOrOperation } from "../utils/ContextualLoggedClass.js";
+import { ClientBasedService } from "../services/services.js";
+import { TaskEngine } from "./TaskEngine.js";
+import { Adapter } from "../persistence/Adapter.js";
+import { type AllOperationKeys, type ContextOf, type EventIds, type ObserverFilter } from "../persistence/types.js";
 import { type PrimaryKeyType } from "@decaf-ts/db-decorators";
-import { OrderDirection } from "../repository/constants";
-import { type Repo } from "../repository/Repository";
-import { TaskModel } from "./models/TaskModel";
-import { type DirectionLimitOffset } from "../query/types";
+import { OrderDirection } from "../repository/constants.js";
+import { type Repo } from "../repository/Repository.js";
+import { TaskModel } from "./models/TaskModel.js";
+import { type DirectionLimitOffset } from "../query/types.js";
 import type { Constructor } from "@decaf-ts/decoration";
-import type { Observer } from "../interfaces/Observer";
-import type { ArrayMode } from "../services/ModelService";
-import { TaskEngineConfig } from "./types";
-import { TaskTracker } from "./TaskTracker";
-import { TaskEventModel } from "./models/index";
-import { SelectSelector, WhereOption } from "../query/index";
+import type { Observer } from "../interfaces/Observer.js";
+import type { ArrayMode } from "../services/ModelService.js";
+import { TaskEngineConfig } from "./types.js";
+import { TaskTracker } from "./TaskTracker.js";
+import { TaskEventModel } from "./models/index.js";
+import { SelectSelector, WhereOption } from "../query/index.js";
 export type TaskServiceConfig<A extends Adapter<any, any, any, any>, T extends TaskEngine<A> = TaskEngine<A>, C extends TaskEngineConfig<A> = TaskEngineConfig<A>> = C & {
     engine?: Constructor<T>;
 };

package/lib/types/tasks/TaskStateChangeError.d.cts

@@ -0,0 +1,11 @@
+import { TaskStatus } from "./constants.cjs";
+import { TaskErrorModel } from "./models/TaskErrorModel.cjs";
+export interface TaskStateChangeRequest {
+    status: TaskStatus;
+    error?: TaskErrorModel;
+    scheduledTo?: Date;
+}
+export declare class TaskStateChangeError extends Error {
+    readonly request: TaskStateChangeRequest;
+    constructor(request: TaskStateChangeRequest);
+}

package/lib/types/tasks/{TaskStateChangeError.d.ts → TaskStateChangeError.d.mts}

@@ -1,5 +1,5 @@
-import { TaskStatus } from "./constants";
-import { TaskErrorModel } from "./models/TaskErrorModel";
+import { TaskStatus } from "./constants.js";
+import { TaskErrorModel } from "./models/TaskErrorModel.js";
 export interface TaskStateChangeRequest {
     status: TaskStatus;
     error?: TaskErrorModel;

package/lib/types/tasks/TaskTracker.d.cts

@@ -0,0 +1,47 @@
+import { Observer } from "../interfaces/Observer.cjs";
+import { TaskEventModel } from "./models/TaskEventModel.cjs";
+import { Logger } from "@decaf-ts/logging";
+import { TaskEventType, TaskStatus } from "./constants.cjs";
+import { EventPipe, LogPipe, LogPipeOptions } from "./types.cjs";
+import { TaskModel } from "./models/TaskModel.cjs";
+import { Context } from "../persistence/index.cjs";
+import { TaskEventBus } from "./TaskEventBus.cjs";
+import { TaskControlError } from "./TaskErrors.cjs";
+export declare class TaskTracker<O = any> implements Observer<[TaskEventModel, Context]> {
+    protected bus: TaskEventBus;
+    private readonly task;
+    protected unregistration: () => void;
+    protected pipes?: Record<TaskEventType, Set<EventPipe>>;
+    private resolved;
+    private terminalContext?;
+    constructor(bus: TaskEventBus, task: TaskModel);
+    resolve(): Promise<O>;
+    wait(): Promise<O>;
+    attach(log: Logger, opts?: LogPipeOptions): void;
+    logs(pipe: LogPipe): void;
+    pipe(pipe: EventPipe, type?: TaskEventType): void;
+    protected succeed(_result?: O): void;
+    protected fail(_error?: TaskControlError): void;
+    protected cancel(evt: TaskEventModel): void;
+    protected retry(): void;
+    protected reschedule(): void;
+    onSucceed(handler: EventPipe): () => void;
+    onFailure(handler: EventPipe): () => void;
+    onCancel(handler: EventPipe): () => void;
+    onUpdate(handler: EventPipe): () => void;
+    private awaitStatusTerminal;
+    private extractOutput;
+    private extractError;
+    private complete;
+    protected isTerminalStatus(status: TaskStatus): boolean;
+    protected track(evt: TaskEventModel, ctx: Context): Promise<void>;
+    private registerStatusHandler;
+    private getTerminalContext;
+    private buildTerminalEvent;
+    private createTaskControlError;
+    private assignNextAction;
+    private getNextAction;
+    private buildMeta;
+    private resolveTerminalState;
+    refresh(evt: TaskEventModel, ctx: Context): Promise<void>;
+}

package/lib/types/tasks/{TaskTracker.d.ts → TaskTracker.d.mts}

@@ -1,12 +1,12 @@
-import { Observer } from "../interfaces/Observer";
-import { TaskEventModel } from "./models/TaskEventModel";
+import { Observer } from "../interfaces/Observer.js";
+import { TaskEventModel } from "./models/TaskEventModel.js";
 import { Logger } from "@decaf-ts/logging";
-import { TaskEventType, TaskStatus } from "./constants";
-import { EventPipe, LogPipe, LogPipeOptions } from "./types";
-import { TaskModel } from "./models/TaskModel";
-import { Context } from "../persistence/index";
-import { TaskEventBus } from "./TaskEventBus";
-import { TaskControlError } from "./TaskErrors";
+import { TaskEventType, TaskStatus } from "./constants.js";
+import { EventPipe, LogPipe, LogPipeOptions } from "./types.js";
+import { TaskModel } from "./models/TaskModel.js";
+import { Context } from "../persistence/index.js";
+import { TaskEventBus } from "./TaskEventBus.js";
+import { TaskControlError } from "./TaskErrors.js";
 export declare class TaskTracker<O = any> implements Observer<[TaskEventModel, Context]> {
     protected bus: TaskEventBus;
     private readonly task;

package/lib/types/tasks/builder.d.cts

@@ -0,0 +1,72 @@
+import { TaskModel } from "./models/TaskModel.cjs";
+import { BackoffStrategy, JitterStrategy, TaskStatus, TaskType } from "./constants.cjs";
+import { TaskBackoffModel } from "./models/index.cjs";
+import { TaskStepSpecModel } from "./models/TaskStepSpecModel.cjs";
+import { Model, ModelArg } from "@decaf-ts/decorator-validation";
+export declare class TaskBackoffBuilder<NESTED extends boolean = false> extends Model {
+    baseMs: number;
+    jitter: JitterStrategy;
+    maxMs: number;
+    strategy: BackoffStrategy;
+    constructor(arg?: ModelArg<TaskBackoffBuilder>);
+    setBaseMs(value: number): this;
+    setJitter(value: JitterStrategy): this;
+    setMaxMs(value: number): this;
+    setStrategy(value: BackoffStrategy): this;
+    build(): NESTED extends false ? TaskBackoffModel : TaskBuilder;
+}
+export declare class TaskBuilder extends Model {
+    protected classification: string;
+    protected name?: string;
+    protected status: TaskStatus;
+    protected atomicity: TaskType;
+    protected backoff: TaskBackoffModel;
+    protected input?: any;
+    protected lock?: string;
+    protected dependencies?: string[];
+    protected maxAttempts: number;
+    setClassification(value: string): this;
+    setName(value: string): this;
+    setAtomicity(value: TaskType): this;
+    setBackoff<V extends TaskBackoffModel>(value?: TaskBackoffModel): V extends TaskBackoffModel ? this : TaskBackoffBuilder<true>;
+    setInput(value: any): this;
+    setLock(value?: string): this;
+    setDependencies(value?: string[]): this;
+    setDependsOn(value?: string[]): this;
+    setMaxAttempts(value: number): this;
+    constructor(arg?: ModelArg<TaskBuilder>);
+    build(): TaskModel<any, any>;
+}
+export declare class TaskStepSpecBuilder {
+    protected parent: CompositeTaskBuilder;
+    protected step: TaskStepSpecModel;
+    constructor(parent: CompositeTaskBuilder, step: TaskStepSpecModel);
+    setClassification(value: string): this;
+    setName(value?: string): this;
+    setInput(value: any): this;
+    setLock(value?: string): this;
+    setDependsOn(value?: string[]): this;
+    addStep(classification: string): TaskStepSpecBuilder;
+    addStep(classification: string, input: any): CompositeTaskBuilder;
+    addStep(classification: string, name: string, input?: any): CompositeTaskBuilder;
+    setSteps(value: TaskStepSpecModel[]): CompositeTaskBuilder;
+    build(): CompositeTaskBuilder;
+}
+export declare class CompositeTaskBuilder extends TaskBuilder {
+    protected steps?: TaskStepSpecModel[];
+    protected stepResults?: TaskStepSpecModel[];
+    constructor(arg?: ModelArg<CompositeTaskBuilder>);
+    setAtomicity(value: TaskType): this;
+    setSteps(value: TaskStepSpecModel[]): this;
+    /**
+     * Backwards compatible:
+     * - addStep(classification, input?)
+     * - addStep(classification, name, input?)
+     *
+     * When called with only `classification`, returns a TaskStepSpecBuilder so
+     * callers can configure the step and then `.build()` back to this builder.
+     */
+    addStep(classification: string): TaskStepSpecBuilder;
+    addStep(classification: string, input: any): this;
+    addStep(classification: string, name: string, input?: any): this;
+}

package/lib/types/tasks/{builder.d.ts → builder.d.mts}

@@ -1,7 +1,7 @@
-import { TaskModel } from "./models/TaskModel";
-import { BackoffStrategy, JitterStrategy, TaskStatus, TaskType } from "./constants";
-import { TaskBackoffModel } from "./models/index";
-import { TaskStepSpecModel } from "./models/TaskStepSpecModel";
+import { TaskModel } from "./models/TaskModel.js";
+import { BackoffStrategy, JitterStrategy, TaskStatus, TaskType } from "./constants.js";
+import { TaskBackoffModel } from "./models/index.js";
+import { TaskStepSpecModel } from "./models/TaskStepSpecModel.js";
 import { Model, ModelArg } from "@decaf-ts/decorator-validation";
 export declare class TaskBackoffBuilder<NESTED extends boolean = false> extends Model {
     baseMs: number;

package/lib/types/tasks/constants.d.cts

@@ -0,0 +1,31 @@
+import { TaskEngineConfig } from "./types.cjs";
+export declare enum TaskStatus {
+    PENDING = "pending",
+    SCHEDULED = "scheduled",
+    RUNNING = "running",
+    FAILED = "failed",
+    SUCCEEDED = "succeeded",
+    CANCELED = "canceled",
+    WAITING_RETRY = "waiting_retry"
+}
+export declare enum BackoffStrategy {
+    EXPONENTIAL = "exponential",
+    FIXED = "fixed"
+}
+export declare enum JitterStrategy {
+    NONE = "none",
+    FULL = "full"
+}
+export declare enum TaskEventType {
+    STATUS = "status",
+    UPDATE = "update",
+    LOG = "log",
+    PROGRESS = "progress",
+    ALL = "all"
+}
+export declare enum TaskType {
+    ATOMIC = "atomic",
+    COMPOSITE = "composite"
+}
+export declare const TasksKey = "tasks";
+export declare const DefaultTaskEngineConfig: TaskEngineConfig<any>;