@decaf-ts/core 0.28.1 → 0.30.0

package/lib/types/index.d.cts

@@ -24,21 +24,21 @@ export * from "./persistence/index.d.cts";
  * @const VERSION
  * @memberOf module:core
  */
-export declare const VERSION = "0.28.0";
+export declare const VERSION = "0.29.0";
 /**
  * @description Represents the current commit hash of the module build.
  * @summary Stores the current git commit hash for the package. The build replaces
  * the placeholder with the actual commit hash at publish time.
  * @const COMMIT
  */
-export declare const COMMIT = "19de947";
+export declare const COMMIT = "53430c1";
 /**
  * @description Represents the full version string of the module.
  * @summary Stores the semver version and commit hash for the package.
  * The build replaces the placeholder with the actual `<version>-<commit>` value at publish time.
  * @const FULL_VERSION
  */
-export declare const FULL_VERSION = "0.28.0-19de947";
+export declare const FULL_VERSION = "0.29.0-53430c1";
 /**
  * @description Stores the current package version
  * @summary A constant representing the version of the core package

package/lib/types/index.d.mts

@@ -24,21 +24,21 @@ export * from "./persistence/index.d.mts";
  * @const VERSION
  * @memberOf module:core
  */
-export declare const VERSION = "0.28.0";
+export declare const VERSION = "0.29.0";
 /**
  * @description Represents the current commit hash of the module build.
  * @summary Stores the current git commit hash for the package. The build replaces
  * the placeholder with the actual commit hash at publish time.
  * @const COMMIT
  */
-export declare const COMMIT = "19de947";
+export declare const COMMIT = "53430c1";
 /**
  * @description Represents the full version string of the module.
  * @summary Stores the semver version and commit hash for the package.
  * The build replaces the placeholder with the actual `<version>-<commit>` value at publish time.
  * @const FULL_VERSION
  */
-export declare const FULL_VERSION = "0.28.0-19de947";
+export declare const FULL_VERSION = "0.29.0-53430c1";
 /**
  * @description Stores the current package version
  * @summary A constant representing the version of the core package

package/lib/types/migrations/MigrationService.d.cts

@@ -44,6 +44,19 @@ export declare class MigrationService<PERSIST extends boolean, A extends Adapter
     protected referencesMigration(candidate: Migration<any, any>, target: ResolvedMigration): boolean;
     protected precedenceHint(migration: Migration<any, any>): string | undefined;
     protected compareByPrecedence(migration1: ResolvedMigration, migration2: ResolvedMigration): number;
+    /**
+     * Compare two migrations by their base version. The base version is the
+     * portion of the version string stripped of prerelease and build identifiers.
+     * If both migrations share the same base, the method returns `0` and the
+     * caller falls back to precedence comparison. When the versioning scheme
+     * cannot split a version, the full version is used as its own base.
+     *
+     * @param migration1 The first migration to compare.
+     * @param migration2 The second migration to compare.
+     * @returns Negative if `migration1` precedes `migration2`, positive if after,
+     *          or `0` when bases are equal.
+     */
+    protected compareByBaseVersion(migration1: ResolvedMigration, migration2: ResolvedMigration): number;
     protected sort(migrations: ResolvedMigration[]): ResolvedMigration[];
     protected resolveMigration(migration: Migration<any, any>): ResolvedMigration;
     protected shouldIncludeMigration(migration: ResolvedMigration, targetFlavour?: string, includeGeneric?: boolean): boolean;

package/lib/types/migrations/MigrationService.d.mts

@@ -44,6 +44,19 @@ export declare class MigrationService<PERSIST extends boolean, A extends Adapter
     protected referencesMigration(candidate: Migration<any, any>, target: ResolvedMigration): boolean;
     protected precedenceHint(migration: Migration<any, any>): string | undefined;
     protected compareByPrecedence(migration1: ResolvedMigration, migration2: ResolvedMigration): number;
+    /**
+     * Compare two migrations by their base version. The base version is the
+     * portion of the version string stripped of prerelease and build identifiers.
+     * If both migrations share the same base, the method returns `0` and the
+     * caller falls back to precedence comparison. When the versioning scheme
+     * cannot split a version, the full version is used as its own base.
+     *
+     * @param migration1 The first migration to compare.
+     * @param migration2 The second migration to compare.
+     * @returns Negative if `migration1` precedes `migration2`, positive if after,
+     *          or `0` when bases are equal.
+     */
+    protected compareByBaseVersion(migration1: ResolvedMigration, migration2: ResolvedMigration): number;
     protected sort(migrations: ResolvedMigration[]): ResolvedMigration[];
     protected resolveMigration(migration: Migration<any, any>): ResolvedMigration;
     protected shouldIncludeMigration(migration: ResolvedMigration, targetFlavour?: string, includeGeneric?: boolean): boolean;

package/lib/types/migrations/MigrationVersioning.d.cts

@@ -4,4 +4,13 @@ export interface MigrationVersioning {
     compare(a: string, b: string): number;
     gt(a: string, b: string): boolean;
     lte(a: string, b: string): boolean;
+    /**
+     * Returns the base portion of a normalized version string with prerelease
+     * and build identifiers stripped. If the versioning scheme cannot split the
+     * version, returns `undefined` so callers treat the full version as its own base.
+     *
+     * @param version The full version string.
+     * @returns The base version, or `undefined` when not applicable.
+     */
+    base?(version: string): string | undefined;
 }

package/lib/types/migrations/MigrationVersioning.d.mts

@@ -4,4 +4,13 @@ export interface MigrationVersioning {
     compare(a: string, b: string): number;
     gt(a: string, b: string): boolean;
     lte(a: string, b: string): boolean;
+    /**
+     * Returns the base portion of a normalized version string with prerelease
+     * and build identifiers stripped. If the versioning scheme cannot split the
+     * version, returns `undefined` so callers treat the full version as its own base.
+     *
+     * @param version The full version string.
+     * @returns The base version, or `undefined` when not applicable.
+     */
+    base?(version: string): string | undefined;
 }

package/lib/types/migrations/SemverMigrationVersioning.d.cts

@@ -5,6 +5,16 @@ export declare class SemverMigrationVersioning implements MigrationVersioning {
     isVersionHint(value: string): boolean;
     normalize(reference: string, precedenceHint?: string): string;
     compare(a: string, b: string): number;
+    /**
+     * Returns the core version (major.minor.patch) of a semver-compliant version.
+     * This base is used to rank declared precedence before comparing prerelease
+     * identifiers. Versions that are not parsable as semver return `undefined`,
+     * causing callers to fall back to identity semantics.
+     *
+     * @param version The full semver version string.
+     * @returns The core version without prerelease/build metadata, or `undefined`.
+     */
+    base(version: string): string | undefined;
     gt(a: string, b: string): boolean;
     lte(a: string, b: string): boolean;
 }

package/lib/types/migrations/SemverMigrationVersioning.d.mts

@@ -5,6 +5,16 @@ export declare class SemverMigrationVersioning implements MigrationVersioning {
     isVersionHint(value: string): boolean;
     normalize(reference: string, precedenceHint?: string): string;
     compare(a: string, b: string): number;
+    /**
+     * Returns the core version (major.minor.patch) of a semver-compliant version.
+     * This base is used to rank declared precedence before comparing prerelease
+     * identifiers. Versions that are not parsable as semver return `undefined`,
+     * causing callers to fall back to identity semantics.
+     *
+     * @param version The full semver version string.
+     * @returns The core version without prerelease/build metadata, or `undefined`.
+     */
+    base(version: string): string | undefined;
     gt(a: string, b: string): boolean;
     lte(a: string, b: string): boolean;
 }

package/lib/types/migrations/StandardMigrationVersioning.d.cts

@@ -7,6 +7,7 @@ export declare class StandardMigrationVersioning implements MigrationVersioning
     isVersionHint(value: string): boolean;
     normalize(reference: string, precedenceHint?: string): string;
     compare(a: string, b: string): number;
+    base(version: string): string | undefined;
     gt(a: string, b: string): boolean;
     lte(a: string, b: string): boolean;
 }

package/lib/types/migrations/StandardMigrationVersioning.d.mts

@@ -7,6 +7,7 @@ export declare class StandardMigrationVersioning implements MigrationVersioning
     isVersionHint(value: string): boolean;
     normalize(reference: string, precedenceHint?: string): string;
     compare(a: string, b: string): number;
+    base(version: string): string | undefined;
     gt(a: string, b: string): boolean;
     lte(a: string, b: string): boolean;
 }

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

@@ -6,6 +6,7 @@ import { TaskErrorModel } from "./models/TaskErrorModel.d.cts";
 import { TaskStatus } from "./constants.d.cts";
 import { TaskStateChangeRequest } from "./TaskStateChangeError.d.cts";
 import { TaskStepSpecModel } from "./models/TaskStepSpecModel.d.cts";
+import { Lock } from "@decaf-ts/transactional-decorators";
 export declare class TaskContext extends Context<TaskFlags> {
     get taskId(): string;
     get logger(): TaskLogger<any>;
@@ -16,6 +17,7 @@ export declare class TaskContext extends Context<TaskFlags> {
     get attempt(): number;
     get progress(): (data: any) => Promise<void>;
     get heartbeat(): () => Promise<void>;
+    get stepWriteLock(): Lock;
     cacheResult(taskId: string, payload: any): void;
     protected changeState(status: TaskStatus, payload?: Partial<TaskStateChangeRequest>): never;
     cancel(reason?: string | Error | TaskErrorModel, details?: any): never;

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

@@ -6,6 +6,7 @@ import { TaskErrorModel } from "./models/TaskErrorModel.d.mts";
 import { TaskStatus } from "./constants.d.mts";
 import { TaskStateChangeRequest } from "./TaskStateChangeError.d.mts";
 import { TaskStepSpecModel } from "./models/TaskStepSpecModel.d.mts";
+import { Lock } from "@decaf-ts/transactional-decorators";
 export declare class TaskContext extends Context<TaskFlags> {
     get taskId(): string;
     get logger(): TaskLogger<any>;
@@ -16,6 +17,7 @@ export declare class TaskContext extends Context<TaskFlags> {
     get attempt(): number;
     get progress(): (data: any) => Promise<void>;
     get heartbeat(): () => Promise<void>;
+    get stepWriteLock(): Lock;
     cacheResult(taskId: string, payload: any): void;
     protected changeState(status: TaskStatus, payload?: Partial<TaskStateChangeRequest>): never;
     cancel(reason?: string | Error | TaskErrorModel, details?: any): never;

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

@@ -79,6 +79,11 @@ export declare class TaskEngine<A extends Adapter<any, any, any, any>, C extends
     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 getCompositeStepConcurrencyLimit(): number;
+    protected isConcurrentCompositeStep(step: TaskStepSpecModel): boolean;
+    protected createCompositeStepContext(context: TaskContext, stepIndex: number): TaskContext;
+    protected withStepWriteLock<T>(ctx: TaskContext, fn: () => Promise<T>): Promise<T>;
+    protected recalculateCompositeCurrentStep(steps: TaskStepSpecModel[], results: TaskStepResultModel[]): number;
     protected executeClaimed(task: TaskModel): Promise<void>;
     protected handleTaskStateChange(request: TaskStateChangeRequest, task: TaskModel, ctx: TaskContext): Promise<void>;
     protected runComposite(task: TaskModel, context: TaskContext): Promise<any>;

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

@@ -79,6 +79,11 @@ export declare class TaskEngine<A extends Adapter<any, any, any, any>, C extends
     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 getCompositeStepConcurrencyLimit(): number;
+    protected isConcurrentCompositeStep(step: TaskStepSpecModel): boolean;
+    protected createCompositeStepContext(context: TaskContext, stepIndex: number): TaskContext;
+    protected withStepWriteLock<T>(ctx: TaskContext, fn: () => Promise<T>): Promise<T>;
+    protected recalculateCompositeCurrentStep(steps: TaskStepSpecModel[], results: TaskStepResultModel[]): number;
     protected executeClaimed(task: TaskModel): Promise<void>;
     protected handleTaskStateChange(request: TaskStateChangeRequest, task: TaskModel, ctx: TaskContext): Promise<void>;
     protected runComposite(task: TaskModel, context: TaskContext): Promise<any>;

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

@@ -45,6 +45,7 @@ export declare class TaskStepSpecBuilder {
     setName(value?: string): this;
     setInput(value: any): this;
     setLock(value?: string): this;
+    setAllowConcurrent(value?: boolean): this;
     setDependsOn(value?: string[]): this;
     setCanFail(value: boolean): this;
     setMaxAttempts(value?: number): this;

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

@@ -45,6 +45,7 @@ export declare class TaskStepSpecBuilder {
     setName(value?: string): this;
     setInput(value: any): this;
     setLock(value?: string): this;
+    setAllowConcurrent(value?: boolean): this;
     setDependsOn(value?: string[]): this;
     setCanFail(value: boolean): this;
     setMaxAttempts(value?: number): this;

package/lib/types/tasks/models/TaskStepSpecModel.d.cts

@@ -5,6 +5,7 @@ export declare class TaskStepSpecModel extends Model {
     name?: string;
     input?: any;
     lock?: string;
+    allowConcurrent: boolean;
     dependsOn?: string[];
     canFail: boolean;
     maxAttempts?: number;

package/lib/types/tasks/models/TaskStepSpecModel.d.mts

@@ -5,6 +5,7 @@ export declare class TaskStepSpecModel extends Model {
     name?: string;
     input?: any;
     lock?: string;
+    allowConcurrent: boolean;
     dependsOn?: string[];
     canFail: boolean;
     maxAttempts?: number;

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

@@ -9,6 +9,7 @@ import { TaskEventModel } from "./models/TaskEventModel.d.cts";
 import { TaskStatus } from "./constants.d.cts";
 import { TaskErrorModel } from "./models/TaskErrorModel.d.cts";
 import { TaskStepSpecModel } from "./models/TaskStepSpecModel.d.cts";
+import { Lock } from "@decaf-ts/transactional-decorators";
 export interface ITaskHandler<I = any, O = any> {
     type: string;
     run(input: I, ctx: TaskContext): Promise<O>;
@@ -31,6 +32,8 @@ export interface LogPipe {
 export interface TaskFlags<LOG extends TaskLogger<any> = TaskLogger<any>> extends ContextFlags<LOG> {
     taskId: string;
     attempt: number;
+    step?: number;
+    stepWriteLock?: Lock;
     pipe: LogPipe;
     flush: () => Promise<void>;
     progress: (data: any) => Promise<void>;
@@ -47,6 +50,7 @@ export type TaskEngineConfig<A extends Adapter<any, any, any, any>> = {
     registry?: TaskHandlerRegistry;
     workerId: string;
     concurrency: number;
+    maxConcurrentCompositeSteps?: number;
     leaseMs: number;
     pollMsIdle: number;
     pollMsBusy: number;

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

@@ -9,6 +9,7 @@ import { TaskEventModel } from "./models/TaskEventModel.d.mts";
 import { TaskStatus } from "./constants.d.mts";
 import { TaskErrorModel } from "./models/TaskErrorModel.d.mts";
 import { TaskStepSpecModel } from "./models/TaskStepSpecModel.d.mts";
+import { Lock } from "@decaf-ts/transactional-decorators";
 export interface ITaskHandler<I = any, O = any> {
     type: string;
     run(input: I, ctx: TaskContext): Promise<O>;
@@ -31,6 +32,8 @@ export interface LogPipe {
 export interface TaskFlags<LOG extends TaskLogger<any> = TaskLogger<any>> extends ContextFlags<LOG> {
     taskId: string;
     attempt: number;
+    step?: number;
+    stepWriteLock?: Lock;
     pipe: LogPipe;
     flush: () => Promise<void>;
     progress: (data: any) => Promise<void>;
@@ -47,6 +50,7 @@ export type TaskEngineConfig<A extends Adapter<any, any, any, any>> = {
     registry?: TaskHandlerRegistry;
     workerId: string;
     concurrency: number;
+    maxConcurrentCompositeSteps?: number;
     leaseMs: number;
     pollMsIdle: number;
     pollMsBusy: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decaf-ts/core",
-  "version": "0.28.1",
+  "version": "0.30.0",
   "description": "Core persistence module for the decaf framework",
   "type": "module",
   "exports": {