@decaf-ts/core 0.20.0 → 0.21.0

package/lib/types/utils/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @description Exports for the utils module.
+ * @summary This file exports all the necessary components for the utils functionality, including the ContextualLoggedClass, decorators, errors, and more.
+ * @module core/utils
+ */
+export * from "./ContextualLoggedClass";
+export * from "./decorators";
+export * from "./errors";
+export * from "./utils";
+export * from "./throttling";
+export * from "./types";

package/lib/types/utils/throttling.d.ts

@@ -0,0 +1,9 @@
+export type BseThrottlingConfig = {
+    delayMs?: number;
+};
+export type ThrottlingConfig = ({
+    count: number;
+} | {
+    bufferSize: number;
+}) & BseThrottlingConfig;
+export declare function throttle(cfg?: ThrottlingConfig | ((...args: any[]) => ThrottlingConfig), argIndex?: number | number[]): (target: object, propertyKey?: any, descriptor?: any) => void;

package/lib/types/utils/types.d.ts

@@ -0,0 +1,23 @@
+export type HttpVerbs = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export type DecafApiProperty = {
+    name: string;
+    description?: string;
+    required?: boolean;
+    type?: any;
+};
+export type DecafModelRoute = {
+    path: string;
+    description?: string;
+    apiProperties: DecafApiProperty[];
+    getPK: (...args: Array<string | number>) => string;
+};
+export type DecafParamProps = {
+    raw: Record<string, string | number>;
+    keysInOrder: Array<string>;
+    valuesInOrder: Array<string | number>;
+};
+export interface DecafRouteDecOptions {
+    path: string;
+    httpMethod: HttpVerbs;
+    handler: PropertyDescriptor;
+}

package/lib/types/utils/utils.d.ts

@@ -0,0 +1,22 @@
+import { BlockOperationKind, CrudOperations } from "@decaf-ts/db-decorators";
+import type { ModelConstructor } from "@decaf-ts/decorator-validation";
+import { Constructor } from "@decaf-ts/decoration";
+export declare function injectableServiceKey(name: string | symbol | Constructor): string;
+export declare function promiseSequence<T>(tasks: (() => Promise<T>)[], continueOnError?: false): Promise<T[]>;
+export declare function promiseSequence<T>(tasks: (() => Promise<T>)[], continueOnError: true): Promise<PromiseSettledResult<T>[]>;
+export declare function isOperationBlocked(ModelConstructor: ModelConstructor<any>, op: CrudOperations): boolean;
+export declare function isOperationBlocked(ModelConstructor: ModelConstructor<any>, kind: BlockOperationKind, value: string): boolean;
+/**
+ * @description Normalizes imports to handle both CommonJS and ESModule formats.
+ * @summary Utility function to handle module import differences between formats.
+ *
+ * @template T - Type of the imported module.
+ * @param {Promise<T>} importPromise - Promise returned by dynamic import.
+ * @return {Promise<T>} Normalized module.
+ *
+ * @function normalizeImport
+ *
+ * @memberOf module:core
+ */
+export declare function normalizeImport<T>(importPromise: Promise<T>): Promise<T>;
+export declare function prefixMethod(obj: any, after: (...args: any[]) => any, prefix: (...args: any[]) => any, afterName?: string): void;

package/lib/types/workers/TaskEngine.d.ts

@@ -0,0 +1,40 @@
+import { Adapter } from "../persistence/Adapter";
+import { ContextOf } from "../persistence/types";
+import { MaybeContextualArg } from "../utils/ContextualLoggedClass";
+import { Constructor } from "@decaf-ts/decoration";
+import { TaskModel } from "../tasks/models/TaskModel";
+import { TaskContext, TaskEngine as TE } from "../tasks";
+import { TaskEngineConfig, TaskWorkerThread, WorkerJobState, WorkThreadPoolConfig } from "./types";
+export declare class TaskEngine<A extends Adapter<any, any, any, any>> extends TE<A, TaskEngineConfig<A>> {
+    protected workerPoolConfig?: WorkThreadPoolConfig;
+    protected workerThreads: TaskWorkerThread[];
+    protected workerJobQueue: WorkerJobState[];
+    protected workerJobs: Map<string, WorkerJobState>;
+    protected workerCounter: number;
+    protected workerThreadCapacity: number;
+    protected get Context(): Constructor<ContextOf<A>>;
+    constructor(config: TaskEngineConfig<A>);
+    private normalizeWorkerPoolConfig;
+    private hasWorkerPool;
+    private getWorkerCount;
+    private getWorkerExecutionSlots;
+    private canDispatchToWorkers;
+    private getExecutionConcurrency;
+    private computeWorkerModules;
+    start(...args: MaybeContextualArg<any>): Promise<void>;
+    stop(...args: MaybeContextualArg<any>): Promise<void>;
+    protected spawnWorkers(): Promise<void>;
+    protected createWorker(): Promise<void> | undefined;
+    private shutdownWorkers;
+    private handleWorkerError;
+    private handleWorkerExit;
+    private handleWorkerMessage;
+    private applyWorkerCache;
+    private processWorkerQueue;
+    private assignWorker;
+    private enqueueWorkerJob;
+    protected runHandlerInline(classification: string, input: any, ctx: TaskContext): Promise<any>;
+    private dispatchToWorker;
+    private invokeHandler;
+    protected executeClaimed(task: TaskModel): Promise<void>;
+}

package/lib/types/workers/WorkThreadEnvironment.d.ts

@@ -0,0 +1,35 @@
+import { TaskEngineAutoShutdownConfig } from "../tasks/types";
+type WorkerMode = "node" | "browser";
+export interface WorkThreadPersistenceConfig {
+    adapterModule: string;
+    adapterClass?: string;
+    adapterArgs?: any[];
+    flavour?: string;
+    alias?: string;
+    modules?: WorkThreadModulesConfig;
+}
+export interface WorkThreadTaskEngineConfig {
+    concurrency: number;
+    leaseMs: number;
+    pollMsIdle: number;
+    pollMsBusy: number;
+    logTailMax: number;
+    streamBufferSize: number;
+    maxLoggingBuffer: number;
+    loggingBufferTruncation: number;
+    gracefulShutdownMsTimeout: number;
+    autoShutdown?: TaskEngineAutoShutdownConfig;
+}
+export interface WorkThreadModulesConfig {
+    imports: string[];
+}
+export interface WorkThreadEnvironmentShape {
+    workerId: string;
+    mode: WorkerMode;
+    persistence: WorkThreadPersistenceConfig;
+    taskEngine: WorkThreadTaskEngineConfig;
+    modules: WorkThreadModulesConfig;
+}
+export declare const DefaultWorkThreadEnvironment: WorkThreadEnvironmentShape;
+export declare const WorkThreadEnvironment: any;
+export {};

package/lib/types/workers/index.d.ts

@@ -0,0 +1,5 @@
+import "../overrides";
+export * from "./messages";
+export * from "./TaskEngine";
+export * from "./types";
+export * from "./WorkThreadEnvironment";

package/lib/types/workers/messages.d.ts

@@ -0,0 +1,69 @@
+import { LogLevel } from "@decaf-ts/logging";
+import { TaskStateChangeRequest } from "../tasks/TaskStateChangeError";
+export type WorkerLogEntry = [LogLevel, string] | [LogLevel, string, any];
+export interface WorkerJobPayload {
+    jobId: string;
+    taskId: string;
+    classification: string;
+    input: any;
+    attempt: number;
+    resultCache?: Record<string, any>;
+    streamBufferSize: number;
+    maxLoggingBuffer: number;
+    loggingBufferTruncation: number;
+}
+export type WorkerToMainMessage = {
+    type: "ready";
+    workerId: string;
+} | {
+    type: "log";
+    workerId: string;
+    jobId: string;
+    entries: WorkerLogEntry[];
+} | {
+    type: "progress";
+    workerId: string;
+    jobId: string;
+    payload: any;
+} | {
+    type: "heartbeat";
+    workerId: string;
+    jobId: string;
+} | {
+    type: "result";
+    workerId: string;
+    jobId: string;
+    status: "success";
+    output: any;
+    cache?: Record<string, any>;
+} | {
+    type: "result";
+    workerId: string;
+    jobId: string;
+    status: "error";
+    error: {
+        name?: string;
+        message: string;
+        stack?: string;
+    };
+    cache?: Record<string, any>;
+} | {
+    type: "result";
+    workerId: string;
+    jobId: string;
+    status: "state-change";
+    request: TaskStateChangeRequest;
+    cache?: Record<string, any>;
+} | {
+    type: "error";
+    workerId: string;
+    error: string;
+    stack?: string;
+};
+export type MainToWorkerMessage = {
+    type: "control";
+    command: "stop" | "shutdown";
+} | {
+    type: "execute";
+    job: WorkerJobPayload;
+};

package/lib/types/workers/types.d.ts

@@ -0,0 +1,41 @@
+import { Worker } from "worker_threads";
+import { TaskContext, TaskModel, TaskEngineConfig as TEC, TaskServiceConfig as TSC } from "../tasks/index";
+export type TaskWorkerThread = {
+    id: string;
+    worker: Worker;
+    ready: boolean;
+    activeJobs: number;
+    capacity: number;
+    readyPromise?: Promise<void>;
+    resolveReady?: () => void;
+    rejectReady?: (error: Error) => void;
+};
+export type WorkerJobState = {
+    id: string;
+    classification: string;
+    input: any;
+    task: TaskModel;
+    ctx: TaskContext;
+    resolve: (value: any) => void;
+    reject: (error: any) => void;
+    worker?: TaskWorkerThread;
+};
+import { WorkThreadModulesConfig, WorkThreadPersistenceConfig } from "./WorkThreadEnvironment";
+import { Adapter } from "../persistence/index";
+export type WorkerAdapterDescriptor = WorkThreadPersistenceConfig;
+export type WorkThreadPoolConfig = {
+    size?: number;
+    mode?: "node" | "browser";
+    entry: string;
+    modules?: WorkThreadModulesConfig;
+};
+export type TaskEngineConfig<A extends Adapter<any, any, any, any>> = TEC<A> & {
+    workerAdapter?: WorkerAdapterDescriptor;
+    workerPool?: WorkThreadPoolConfig;
+    workerConcurrency?: number;
+};
+export type TaskServiceConfig<A extends Adapter<any, any, any, any>> = TSC<A> & {
+    workerAdapter?: WorkerAdapterDescriptor;
+    workerPool?: WorkThreadPoolConfig;
+    workerConcurrency?: number;
+};

package/lib/types/workers/workerThread.d.ts

@@ -0,0 +1 @@
+import "../overrides";

package/package.json

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