@decaf-ts/core 0.8.51 → 0.8.53

package/lib/esm/fs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/fs/index.ts"],"names":[],"mappings":"AAAA,uCAAoC;AACpC,2BAAwB;AACxB,6BAA0B;AAC1B,gCAA6B"}

package/lib/esm/fs/indexStore.d.ts

@@ -0,0 +1,28 @@
+import type { promises as FsPromises } from "node:fs";
+import { PrimaryKeyType } from "@decaf-ts/db-decorators";
+import { OrderDirection } from "../repository/constants";
+import { JsonSpacing } from "./helpers";
+export type IndexDescriptor = {
+    name: string;
+    fileName: string;
+    columns: string[];
+    directions?: OrderDirection[2];
+};
+export declare function toIndexFileName(indexName: string): string;
+export declare class FsIndexStore {
+    private readonly fs;
+    private readonly indexDirResolver;
+    private readonly spacing?;
+    private readonly cache;
+    constructor(fs: typeof FsPromises, indexDirResolver: (tableName: string) => string, spacing?: JsonSpacing);
+    ensure(tableName: string, descriptors: IndexDescriptor[]): Promise<void>;
+    upsert(tableName: string, descriptors: IndexDescriptor[], id: PrimaryKeyType, record: Record<string, any>, previous?: Record<string, any>): Promise<void>;
+    remove(tableName: string, descriptors: IndexDescriptor[], id: PrimaryKeyType, record?: Record<string, any>): Promise<void>;
+    private removeFromEntries;
+    private removeFromAll;
+    private keyForRecord;
+    private normalizeValue;
+    private indexPath;
+    private persist;
+    refresh(tableName: string, descriptors: IndexDescriptor[]): Promise<void>;
+}

package/lib/esm/fs/indexStore.js

@@ -0,0 +1,173 @@
+import path from "node:path";
+import { ensureDir, readJsonFile, serializeId, writeJsonAtomic, } from "./helpers.js";
+const KEY_SEPARATOR = "::";
+export function toIndexFileName(indexName) {
+    return encodeURIComponent(indexName).replace(/%/g, "_");
+}
+export class FsIndexStore {
+    constructor(fs, indexDirResolver, spacing) {
+        this.fs = fs;
+        this.indexDirResolver = indexDirResolver;
+        this.spacing = spacing;
+        this.cache = new Map();
+    }
+    async ensure(tableName, descriptors) {
+        if (!descriptors.length)
+            return;
+        await ensureDir(this.fs, this.indexDirResolver(tableName));
+        if (!this.cache.has(tableName))
+            this.cache.set(tableName, new Map());
+        const tableCache = this.cache.get(tableName);
+        await Promise.all(descriptors.map(async (descriptor) => {
+            if (tableCache.has(descriptor.fileName))
+                return;
+            const filePath = this.indexPath(tableName, descriptor.fileName);
+            const existing = await readJsonFile(this.fs, filePath);
+            const payload = existing && existing.columns?.length
+                ? {
+                    ...descriptor,
+                    entries: existing.entries ?? {},
+                    directions: existing.directions ?? descriptor.directions,
+                    columns: existing.columns,
+                }
+                : {
+                    ...descriptor,
+                    entries: {},
+                };
+            tableCache.set(descriptor.fileName, payload);
+        }));
+    }
+    async upsert(tableName, descriptors, id, record, previous) {
+        if (!descriptors.length)
+            return;
+        await this.ensure(tableName, descriptors);
+        const tableCache = this.cache.get(tableName);
+        if (!tableCache)
+            return;
+        const serializedId = serializeId(id);
+        await Promise.all(descriptors.map(async (descriptor) => {
+            const payload = tableCache.get(descriptor.fileName);
+            if (!payload)
+                return;
+            if (previous) {
+                const prevKey = this.keyForRecord(previous, descriptor.columns);
+                if (prevKey) {
+                    this.removeFromEntries(payload.entries, prevKey, serializedId);
+                }
+            }
+            const nextKey = this.keyForRecord(record, descriptor.columns);
+            if (!nextKey)
+                return;
+            const bucket = payload.entries[nextKey] ?? [];
+            if (!bucket.find((entry) => entry.type === serializedId.type && entry.value === serializedId.value)) {
+                bucket.push(serializedId);
+                payload.entries[nextKey] = bucket;
+            }
+            await this.persist(tableName, payload);
+        }));
+    }
+    async remove(tableName, descriptors, id, record) {
+        if (!descriptors.length)
+            return;
+        await this.ensure(tableName, descriptors);
+        const tableCache = this.cache.get(tableName);
+        if (!tableCache)
+            return;
+        const serializedId = serializeId(id);
+        await Promise.all(descriptors.map(async (descriptor) => {
+            const payload = tableCache.get(descriptor.fileName);
+            if (!payload)
+                return;
+            let removed = false;
+            if (record) {
+                const key = this.keyForRecord(record, descriptor.columns);
+                if (key) {
+                    removed = this.removeFromEntries(payload.entries, key, serializedId);
+                }
+            }
+            if (!removed) {
+                removed = this.removeFromAll(payload.entries, serializedId);
+            }
+            if (removed) {
+                await this.persist(tableName, payload);
+            }
+        }));
+    }
+    removeFromEntries(entries, key, id) {
+        const bucket = entries[key];
+        if (!bucket)
+            return false;
+        const filtered = bucket.filter((entry) => entry.value !== id.value || entry.type !== id.type);
+        if (filtered.length) {
+            entries[key] = filtered;
+        }
+        else {
+            delete entries[key];
+        }
+        return filtered.length !== bucket.length;
+    }
+    removeFromAll(entries, id) {
+        let removed = false;
+        for (const key of Object.keys(entries)) {
+            removed = this.removeFromEntries(entries, key, id) || removed;
+        }
+        return removed;
+    }
+    keyForRecord(record, columns) {
+        if (!record)
+            return undefined;
+        const values = [];
+        for (const column of columns) {
+            if (!(column in record) || typeof record[column] === "undefined") {
+                return undefined;
+            }
+            values.push(record[column]);
+        }
+        return values.map(this.normalizeValue).join(KEY_SEPARATOR);
+    }
+    normalizeValue(value) {
+        if (value === null)
+            return "__null__";
+        if (value === undefined)
+            return "__undefined__";
+        if (typeof value === "object") {
+            try {
+                return JSON.stringify(value);
+            }
+            catch {
+                return String(value);
+            }
+        }
+        return String(value);
+    }
+    indexPath(tableName, fileName) {
+        return path.join(this.indexDirResolver(tableName), `${fileName}.json`);
+    }
+    async persist(tableName, payload) {
+        const filePath = this.indexPath(tableName, payload.fileName);
+        await writeJsonAtomic(this.fs, filePath, payload, this.spacing);
+    }
+    async refresh(tableName, descriptors) {
+        if (!descriptors.length)
+            return;
+        await this.ensure(tableName, descriptors);
+        const tableCache = this.cache.get(tableName);
+        if (!tableCache)
+            return;
+        await Promise.all(descriptors.map(async (descriptor) => {
+            const filePath = this.indexPath(tableName, descriptor.fileName);
+            const payload = await readJsonFile(this.fs, filePath);
+            if (!payload) {
+                tableCache.delete(descriptor.fileName);
+                return;
+            }
+            const refreshed = {
+                ...descriptor,
+                entries: payload.entries ?? {},
+                directions: payload.directions ?? descriptor.directions,
+            };
+            tableCache.set(descriptor.fileName, refreshed);
+        }));
+    }
+}
+//# sourceMappingURL=indexStore.js.map

package/lib/esm/fs/indexStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexStore.js","sourceRoot":"","sources":["../../../src/fs/indexStore.ts"],"names":[],"mappings":"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"}

package/lib/esm/fs/locks/FilesystemLock.d.ts

@@ -0,0 +1,13 @@
+import { promises as defaultFs } from "node:fs";
+import { Lock } from "@decaf-ts/transactional-decorators";
+export declare class FilesystemLock extends Lock {
+    private readonly lockPath;
+    private readonly fs;
+    private readonly waitMs;
+    private handle?;
+    constructor(lockPath: string, fs?: typeof defaultFs, waitMs?: number);
+    private takeLock;
+    private releaseLockFile;
+    acquire(...args: any[]): Promise<void>;
+    release(...args: any[]): void;
+}

package/lib/esm/fs/locks/FilesystemLock.js

@@ -0,0 +1,49 @@
+import { promises as defaultFs, constants as fsConstants } from "node:fs";
+import path from "node:path";
+import { Lock } from "@decaf-ts/transactional-decorators";
+import { ensureDir } from "./../helpers.js";
+const DEFAULT_WAIT_MS = 50;
+export class FilesystemLock extends Lock {
+    constructor(lockPath, fs = defaultFs, waitMs = DEFAULT_WAIT_MS) {
+        super();
+        this.lockPath = lockPath;
+        this.fs = fs;
+        this.waitMs = waitMs;
+    }
+    async takeLock() {
+        await ensureDir(this.fs, path.dirname(this.lockPath));
+        while (true) {
+            try {
+                this.handle = await this.fs.open(this.lockPath, fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_RDWR);
+                return;
+            }
+            catch (err) {
+                if (err?.code === "EEXIST") {
+                    await new Promise((resolve) => setTimeout(resolve, this.waitMs));
+                    continue;
+                }
+                throw err;
+            }
+        }
+    }
+    async releaseLockFile() {
+        if (!this.handle)
+            return;
+        try {
+            await this.handle.close();
+        }
+        catch {
+            // ignore errors while closing
+        }
+        await this.fs.rm(this.lockPath, { force: true });
+        this.handle = undefined;
+    }
+    async acquire(...args) {
+        await super.acquire(...args);
+        await this.takeLock();
+    }
+    release(...args) {
+        void this.releaseLockFile().then(() => super.release(...args));
+    }
+}
+//# sourceMappingURL=FilesystemLock.js.map

package/lib/esm/fs/locks/FilesystemLock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FilesystemLock.js","sourceRoot":"","sources":["../../../../src/fs/locks/FilesystemLock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,SAAS,EAAE,SAAS,IAAI,WAAW,EAAE,MAAM,SAAS,CAAC;AAC1E,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,wBAAmB;AAEvC,MAAM,eAAe,GAAG,EAAE,CAAC;AAE3B,MAAM,OAAO,cAAe,SAAQ,IAAI;IAGtC,YACmB,QAAgB,EAChB,KAAuB,SAAS,EAChC,SAAiB,eAAe;QAEjD,KAAK,EAAE,CAAC;QAJS,aAAQ,GAAR,QAAQ,CAAQ;QAChB,OAAE,GAAF,EAAE,CAA8B;QAChC,WAAM,GAAN,MAAM,CAA0B;IAGnD,CAAC;IAEO,KAAK,CAAC,QAAQ;QACpB,MAAM,SAAS,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;QACtD,OAAO,IAAI,EAAE,CAAC;YACZ,IAAI,CAAC;gBACH,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,IAAI,CAC9B,IAAI,CAAC,QAAQ,EACb,WAAW,CAAC,OAAO,GAAG,WAAW,CAAC,MAAM,GAAG,WAAW,CAAC,MAAM,CAC9D,CAAC;gBACF,OAAO;YACT,CAAC;YAAC,OAAO,GAAQ,EAAE,CAAC;gBAClB,IAAI,GAAG,EAAE,IAAI,KAAK,QAAQ,EAAE,CAAC;oBAC3B,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;oBACjE,SAAS;gBACX,CAAC;gBACD,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,eAAe;QAC3B,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,OAAO;QACzB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QAC5B,CAAC;QAAC,MAAM,CAAC;YACP,8BAA8B;QAChC,CAAC;QACD,MAAM,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACjD,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;IAC1B,CAAC;IAEQ,KAAK,CAAC,OAAO,CAAC,GAAG,IAAW;QACnC,MAAM,KAAK,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;QAC7B,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;IACxB,CAAC;IAEQ,OAAO,CAAC,GAAG,IAAW;QAC7B,KAAK,IAAI,CAAC,eAAe,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IACjE,CAAC;CACF"}

package/lib/esm/fs/locks/FilesystemMultiLock.d.ts

@@ -0,0 +1,8 @@
+import { promises as defaultFs } from "node:fs";
+import { MultiLock, Lock } from "@decaf-ts/transactional-decorators";
+export declare class FilesystemMultiLock extends MultiLock {
+    private readonly lockDir;
+    private readonly fs;
+    constructor(lockDir: string, fs?: typeof defaultFs);
+    protected lockFor(name: string): Promise<Lock>;
+}

package/lib/esm/fs/locks/FilesystemMultiLock.js

@@ -0,0 +1,23 @@
+import { promises as defaultFs } from "node:fs";
+import path from "node:path";
+import { MultiLock } from "@decaf-ts/transactional-decorators";
+import { ensureDir } from "./../helpers.js";
+import { FilesystemLock } from "./FilesystemLock.js";
+export class FilesystemMultiLock extends MultiLock {
+    constructor(lockDir, fs = defaultFs) {
+        super();
+        this.lockDir = lockDir;
+        this.fs = fs;
+    }
+    async lockFor(name) {
+        await this.lock.acquire();
+        if (!this.locks[name]) {
+            const lockPath = path.join(this.lockDir, `${encodeURIComponent(name)}.lock`);
+            await ensureDir(this.fs, path.dirname(lockPath));
+            this.locks[name] = new FilesystemLock(lockPath, this.fs);
+        }
+        this.lock.release();
+        return this.locks[name];
+    }
+}
+//# sourceMappingURL=FilesystemMultiLock.js.map

package/lib/esm/fs/locks/FilesystemMultiLock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FilesystemMultiLock.js","sourceRoot":"","sources":["../../../../src/fs/locks/FilesystemMultiLock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,SAAS,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAQ,MAAM,oCAAoC,CAAC;AACrE,OAAO,EAAE,SAAS,EAAE,wBAAmB;AACvC,OAAO,EAAE,cAAc,EAAE,4BAAyB;AAElD,MAAM,OAAO,mBAAoB,SAAQ,SAAS;IAChD,YACmB,OAAe,EACf,KAAuB,SAAS;QAEjD,KAAK,EAAE,CAAC;QAHS,YAAO,GAAP,OAAO,CAAQ;QACf,OAAE,GAAF,EAAE,CAA8B;IAGnD,CAAC;IAEkB,KAAK,CAAC,OAAO,CAAC,IAAY;QAC3C,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QAC1B,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACtB,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CACxB,IAAI,CAAC,OAAO,EACZ,GAAG,kBAAkB,CAAC,IAAI,CAAC,OAAO,CACnC,CAAC;YACF,MAAM,SAAS,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;YACjD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,cAAc,CAAC,QAAQ,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;QAC3D,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;CACF"}

package/lib/esm/fs/types.d.ts

@@ -0,0 +1,34 @@
+import type { promises as FsPromises } from "node:fs";
+import type { RamConfig } from "../ram/types";
+import type { JsonSpacing } from "./helpers";
+export type FilesystemHydrationInfo = {
+    table: string;
+    records: number;
+};
+export type FilesystemConfig = RamConfig & {
+    /**
+     * Base directory where adapter data is persisted.
+     * A sub-directory using the adapter alias will be created automatically.
+    */
+    rootDir?: string;
+    /**
+     * Optional fs/promises implementation (for testing/mocking).
+     */
+    fs?: typeof FsPromises;
+    /**
+     * Whether JSON files should use pretty formatting.
+     */
+    jsonSpacing?: JsonSpacing;
+    /**
+     * Optional callback invoked after a table has been hydrated from disk.
+     */
+    onHydrated?: (info: FilesystemHydrationInfo) => void;
+    /**
+     * Directory used to store lockfiles when filesystem locking is enabled.
+     */
+    lockDir?: string;
+    /**
+     * Minimum debounce window (in milliseconds) used by watchers before notifying observers.
+     */
+    watchDebounceMs?: number;
+};

package/lib/esm/fs/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/lib/esm/fs/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/fs/types.ts"],"names":[],"mappings":""}

package/lib/esm/index.d.ts

@@ -22,7 +22,7 @@ export * from "./persistence";
  * @const VERSION
  * @memberOf module:core
  */
-export declare const VERSION = "0.8.50";
+export declare const VERSION = "0.8.52";
 /**
  * @description Stores the current package version
  * @summary A constant representing the version of the core package

package/lib/esm/index.js

@@ -32,7 +32,7 @@ export * from "./persistence/index.js";
  * @const VERSION
  * @memberOf module:core
  */
-export const VERSION = "0.8.50";
+export const VERSION = "0.8.52";
 /**
  * @description Stores the current package version
  * @summary A constant representing the version of the core package

package/lib/esm/ram/RamAdapter.d.ts

@@ -235,7 +235,7 @@ export declare class RamAdapter extends Adapter<RamConfig, RamStorage, RawRamQue
      * @param {Constructor<M>} from - The model class
      * @return {Map<string | number, any> | undefined} The table Map or undefined
      */
-    protected tableFor<M extends Model>(from: Constructor<M>): Map<string | number, any> | undefined;
+    protected tableFor<M extends Model>(from: Constructor<M>): Map<PrimaryKeyType, any> | undefined;
     /**
      * @description Executes a raw query against the in-memory storage
      * @summary Performs a query operation on the in-memory data store using the provided query specification.

package/lib/esm/ram/types.d.ts

@@ -4,6 +4,7 @@ import { Constructor } from "@decaf-ts/decoration";
 import { Adapter, AdapterFlags } from "../persistence";
 import { Context } from "../persistence/Context";
 import { MultiLock } from "@decaf-ts/transactional-decorators";
+import { PrimaryKeyType } from "@decaf-ts/db-decorators";
 /**
  * @description In-memory storage structure for the RAM adapter
  * @summary A nested Map structure that stores all entities by their table name and primary key.
@@ -12,7 +13,7 @@ import { MultiLock } from "@decaf-ts/transactional-decorators";
  * @memberOf module:core
  * @category Ram
  */
-export type RamStorage = Map<string, Map<string | number, any>>;
+export type RamStorage = Map<string, Map<PrimaryKeyType, any>>;
 export type RawRamQuery<M extends Model = any> = {
     select: undefined | (keyof M)[];
     from: Constructor<M>;

package/lib/esm/tasks/TaskEngine.d.ts

@@ -4,17 +4,25 @@ import { TaskEventModel } from "./models/TaskEventModel";
 import { TaskHandlerRegistry } from "./TaskHandlerRegistry";
 import { TaskEventBus } from "./TaskEventBus";
 import { Adapter } from "../persistence/Adapter";
+import { Context } from "../persistence/Context";
 import { ContextOf, FlagsOf } from "../persistence/types";
 import { AbsContextual, MaybeContextualArg } from "../utils/ContextualLoggedClass";
 import { OperationKeys } from "@decaf-ts/db-decorators";
+import { TaskContext } from "./TaskContext";
 import { DateTarget } from "@decaf-ts/decorator-validation";
 import { Constructor } from "@decaf-ts/decoration";
-import { TaskEngineConfig } from "./types";
+import { TaskEngineConfig, TaskFlags } from "./types";
 import { TaskTracker } from "./TaskTracker";
 export declare class TaskEngine<A extends Adapter<any, any, any, any>> extends AbsContextual<ContextOf<A>> {
     private config;
     private _tasks?;
     private _events?;
+    private workerPoolConfig?;
+    private workerThreads;
+    private workerJobQueue;
+    private workerJobs;
+    private workerCounter;
+    private workerThreadCapacity;
     private lock;
     protected get Context(): Constructor<ContextOf<A>>;
     protected get adapter(): A;
@@ -23,7 +31,15 @@ export declare class TaskEngine<A extends Adapter<any, any, any, any>> extends A
     protected get tasks(): Repo<TaskModel>;
     protected get events(): Repo<TaskEventModel>;
     protected running: boolean;
+    static createTaskContext(base?: Context<any>, overrides?: Partial<TaskFlags>): TaskContext;
     constructor(config: TaskEngineConfig<A>);
+    private normalizeWorkerPoolConfig;
+    private hasWorkerPool;
+    private getWorkerCount;
+    private getWorkerExecutionSlots;
+    private canDispatchToWorkers;
+    private getExecutionConcurrency;
+    private computeWorkerModules;
     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<{
@@ -51,9 +67,22 @@ export declare class TaskEngine<A extends Adapter<any, any, any, any>> extends A
     isRunning(): Promise<boolean>;
     start(...args: MaybeContextualArg<any>): Promise<void>;
     stop(...args: MaybeContextualArg<any>): Promise<void>;
+    private spawnWorkers;
+    private createWorker;
+    private shutdownWorkers;
+    private handleWorkerError;
+    private handleWorkerExit;
+    private handleWorkerMessage;
+    private applyWorkerCache;
+    private processWorkerQueue;
+    private assignWorker;
+    private enqueueWorkerJob;
     private loop;
     private claimBatch;
     private tryClaim;
+    private runHandlerInline;
+    private dispatchToWorker;
+    private invokeHandler;
     private executeClaimed;
     private handleTaskStateChange;
     private runComposite;