@hotmeshio/hotmesh 0.0.51 → 0.0.53

package/build/types/stream.d.ts

@@ -1,18 +1,38 @@
+/** Represents a policy for retrying stream operations based on error codes */
 export interface StreamRetryPolicy {
-    [key: string]: [number, 'x'];
+    /**
+     * Key is error code, value is the retry profile.
+     * Tuple contains: [max retry count, retry type].
+     * 'x' denotes exponential backoff (default). Only 10, 100, 1000, 10000 are allowed retry intervals.
+     */
+    [key: string]: [number, 'x'?];
 }
+/** A 3-digit status code representing the outcome of a stream operation */
 export type StreamCode = number;
+/** Describes the structure of a stream error */
 export type StreamError = {
+    /** Descriptive message of the error */
     message: string;
+    /** Numeric code corresponding to the type of error */
     code: number;
+    /** Optional job identifier, used when communicating errors externally */
     job_id?: string;
+    /** Stack trace of the error if unhandled */
     stack?: string;
+    /** Name of the error if unhandled */
     name?: string;
+    /** Custom user-defined error details */
     error?: Record<string, unknown>;
+    /** True if originating via a standard transition message with an `error` status */
+    is_stream_error?: boolean;
 };
+/** Enumerated status values for stream operations */
 export declare enum StreamStatus {
+    /** Indicates successful completion of the stream operation */
     SUCCESS = "success",
+    /** Indicates an error occurred during the stream operation */
     ERROR = "error",
+    /** Indicates the stream operation is still pending */
     PENDING = "pending"
 }
 export declare enum StreamDataType {
@@ -26,27 +46,51 @@ export declare enum StreamDataType {
     SIGNAL = "signal",
     INTERRUPT = "interrupt"
 }
+/** Defines the structure of stream data used when passing stream messages (transitions) */
 export interface StreamData {
+    /** Metadata associated with the stream data */
     metadata: {
+        /** Globally unique identifier for the StreamData message to distinguish `retries` from new 'reentry/cycles' */
         guid: string;
+        /** Workflow/job topic */
         topic?: string;
+        /** Workflow/job ID */
         jid?: string;
+        /** Workflow Generational ID (internal GUID) */
         gid?: string;
+        /** Dimensional address indicating the message routing specifics */
         dad?: string;
+        /** Activity ID */
         aid: string;
+        /** OpenTelemetry Trace identifier */
         trc?: string;
+        /** OpenTelemetry Span identifier */
         spn?: string;
+        /** Current try count, used for retry logic */
         try?: number;
+        /**
+         * Indicates if the message should wait for a response.
+         * If explicitly false, the connection is severed immediately
+         * upon verifying (and returning) the Job ID.
+         */
         await?: boolean;
     };
+    /** Type of the data being streamed, optional */
     type?: StreamDataType;
+    /** Actual data being transmitted as a record of key-value pairs */
     data: Record<string, unknown>;
+    /** Policies related to retry logic, optional */
     policies?: {
         retry?: StreamRetryPolicy;
     };
+    /** Status of the stream, default assumed as 'success' */
     status?: StreamStatus;
+    /** HTTP-like status code for the stream, default assumed as 200 */
     code?: number;
+    /** Error stack trace */
+    stack?: string;
 }
+/** Extends StreamData for responses, allowing for inheritance of the base properties */
 export interface StreamDataResponse extends StreamData {
 }
 export declare enum StreamRole {
@@ -54,19 +98,35 @@ export declare enum StreamRole {
     ENGINE = "engine",
     SYSTEM = "system"
 }
+/**
+ * Represents a type for messages that have been reclaimed from a stream.
+ * Each item is a tuple containing a messageId and its details.
+ */
 export type ReclaimedMessageType = [
+    /** The stream ID, typically formatted as `<timestamp>-<count>` */
     messageId: string,
+    /** Details of the message, consisting of a key and its value */
     details: [
+        /** Key is always 'message' */
         key: string,
+        /** Value is a stringified representation of StreamData */
         value: string
     ]
 ][];
+/** Configuration parameters for a stream */
 export type StreamConfig = {
+    /** Namespace under which the stream operates */
     namespace: string;
+    /** Application identifier */
     appId: string;
+    /** Globally unique identifier for the stream */
     guid: string;
+    /** Role associated with the stream */
     role: StreamRole;
+    /** Optional topic for the stream */
     topic?: string;
+    /** Delay before a message can be reclaimed, defaults to 60,000 milliseconds */
     reclaimDelay?: number;
+    /** Maximum number of reclaims allowed, defaults to 3. Values greater throw an error */
     reclaimCount?: number;
 };

package/build/types/stream.js

@@ -1,10 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StreamRole = exports.StreamDataType = exports.StreamStatus = void 0;
+/** Enumerated status values for stream operations */
 var StreamStatus;
 (function (StreamStatus) {
+    /** Indicates successful completion of the stream operation */
     StreamStatus["SUCCESS"] = "success";
+    /** Indicates an error occurred during the stream operation */
     StreamStatus["ERROR"] = "error";
+    /** Indicates the stream operation is still pending */
     StreamStatus["PENDING"] = "pending";
 })(StreamStatus = exports.StreamStatus || (exports.StreamStatus = {}));
 var StreamDataType;

package/index.ts

@@ -1,7 +1,6 @@
 import { Durable } from './services/durable';
-import { MeshOSService as MeshOS } from './services/durable/meshos';
 import { HotMeshService as HotMesh } from './services/hotmesh';
 import { HotMeshConfig } from './types/hotmesh';
 
-export { Durable, HotMesh, HotMeshConfig, MeshOS };
+export { Durable, HotMesh, HotMeshConfig };
 export * as Types from './types';

package/modules/enums.ts

@@ -3,7 +3,7 @@ import { LogLevel } from "../types/logger";
 // HOTMESH SYSTEM
 export const HMSH_LOGLEVEL = process.env.HMSH_LOGLEVEL as LogLevel || 'info';
 
-// STATUS CODES AND MESSAGES
+// HOTMESH STATUS CODES
 export const HMSH_CODE_SUCCESS = 200;
 export const HMSH_CODE_PENDING = 202;
 export const HMSH_CODE_NOTFOUND = 404;
@@ -11,15 +11,18 @@ export const HMSH_CODE_INTERRUPT = 410;
 export const HMSH_CODE_UNKNOWN = 500;
 export const HMSH_CODE_TIMEOUT = 504;
 export const HMSH_CODE_UNACKED = 999;
-
-export const HMSH_CODE_DURABLE_SLEEPFOR = 592;
-export const HMSH_CODE_DURABLE_INCOMPLETE = 593;
-export const HMSH_CODE_DURABLE_WAITFOR = 594;
+// DURABLE STATUS CODES
+export const HMSH_CODE_DURABLE_SLEEP = 588;
+export const HMSH_CODE_DURABLE_ALL = 589;
+export const HMSH_CODE_DURABLE_CHILD = 590;
+export const HMSH_CODE_DURABLE_PROXY = 591;
+export const HMSH_CODE_DURABLE_WAIT = 595;
 export const HMSH_CODE_DURABLE_TIMEOUT = 596;
 export const HMSH_CODE_DURABLE_MAXED = 597;
 export const HMSH_CODE_DURABLE_FATAL = 598;
 export const HMSH_CODE_DURABLE_RETRYABLE = 599;
 
+// HOTMESH MESSAGES
 export const HMSH_STATUS_UNKNOWN = 'unknown';
 
 // QUORUM
@@ -36,8 +39,13 @@ export const HMSH_MAX_RETRIES = parseInt(process.env.HMSH_MAX_RETRIES, 10) || 3;
 export const HMSH_MAX_TIMEOUT_MS = parseInt(process.env.HMSH_MAX_TIMEOUT_MS, 10) || 60000;
 export const HMSH_GRADUATED_INTERVAL_MS = parseInt(process.env.HMSH_GRADUATED_INTERVAL_MS, 10) || 5000;
 
-const BASE_BLOCK_DURATION = 10000; // Modified for clarity
-const TEST_BLOCK_DURATION = 1000; // Modified for clarity
+// DURABLE
+export const HMSH_DURABLE_MAX_ATTEMPTS =  3;
+export const HMSH_DURABLE_MAX_INTERVAL = '120s';
+export const HMSH_DURABLE_EXP_BACKOFF = 10;
+
+const BASE_BLOCK_DURATION = 10000;
+const TEST_BLOCK_DURATION = 1000;
 export const HMSH_BLOCK_TIME_MS = process.env.HMSH_BLOCK_TIME_MS ? parseInt(process.env.HMSH_BLOCK_TIME_MS, 10) : (process.env.NODE_ENV === 'test' ? TEST_BLOCK_DURATION : BASE_BLOCK_DURATION);
 
 export const HMSH_XCLAIM_DELAY_MS = parseInt(process.env.HMSH_XCLAIM_DELAY_MS, 10) || 1000 * 60;
@@ -48,7 +56,7 @@ export const HMSH_XPENDING_COUNT = parseInt(process.env.HMSH_XPENDING_COUNT, 10)
 export const HMSH_EXPIRE_DURATION = parseInt(process.env.HMSH_EXPIRE_DURATION, 10) || 1;
 
 const BASE_FIDELITY_SECONDS = 5;
-const TEST_FIDELITY_SECONDS = 5;
+const TEST_FIDELITY_SECONDS = 1;
 export const HMSH_FIDELITY_SECONDS = process.env.HMSH_FIDELITY_SECONDS ? parseInt(process.env.HMSH_FIDELITY_SECONDS, 10) : (process.env.NODE_ENV === 'test' ? TEST_FIDELITY_SECONDS : BASE_FIDELITY_SECONDS);
 
 export const HMSH_SCOUT_INTERVAL_SECONDS = parseInt(process.env.HMSH_SCOUT_INTERVAL_SECONDS, 10) || 60;

package/modules/errors.ts

@@ -4,11 +4,13 @@ import {
   HMSH_CODE_DURABLE_MAXED,
   HMSH_CODE_DURABLE_TIMEOUT,
   HMSH_CODE_DURABLE_FATAL,
-  HMSH_CODE_DURABLE_INCOMPLETE,
   HMSH_CODE_NOTFOUND,
   HMSH_CODE_DURABLE_RETRYABLE,
-  HMSH_CODE_DURABLE_SLEEPFOR,
-  HMSH_CODE_DURABLE_WAITFOR } from "./enums";
+  HMSH_CODE_DURABLE_WAIT,
+  HMSH_CODE_DURABLE_PROXY,
+  HMSH_CODE_DURABLE_CHILD,
+  HMSH_CODE_DURABLE_ALL,
+  HMSH_CODE_DURABLE_SLEEP } from "./enums";
 
 class GetStateError extends Error {
   jobId: string;
@@ -24,65 +26,201 @@ class SetStateError extends Error {
   }
 }
 
-//thrown when a signal set is incomplete but already configured
-//if a waitFor set has 'n' items, this can be thrown `n - 1` times
-class DurableIncompleteSignalError extends Error {
+class DurableWaitForError extends Error {
   code: number;
-  constructor(message: string) {
-    super(message);
-    this.code = HMSH_CODE_DURABLE_INCOMPLETE;
+  signalId: string;
+  workflowId: string;
+  index: number;
+  workflowDimension: string; //hook workflowDimension (e.g., ',0,1,0') (use empty string for `null`)
+  constructor(params: {
+    signalId: string,
+    index: number,
+    workflowDimension: string
+    workflowId: string;
+  }) {
+    super(`Durable WaitFor Error [${params.workflowId}]`);
+    this.signalId = params.signalId;
+    this.index = params.index;
+    this.workflowDimension = params.workflowDimension;
+    this.code = HMSH_CODE_DURABLE_WAIT;
   }
 }
 
-//the original waitFor error that is thrown for a new signal set
-class DurableWaitForSignalError extends Error {
+class DurableProxyError extends Error {
+  activityName: string;
+  arguments: string[];
+  backoffCoefficient: number;
   code: number;
-  signals: {signal: string, index: number}[]; //signal id and execution order in the workflow
-  constructor(message: string, signals: {signal: string, index: number}[]) {
-    super(message);
-    this.signals = signals;
-    this.code = HMSH_CODE_DURABLE_WAITFOR;
+  index: number;
+  maximumAttempts: number;
+  maximumInterval: number;
+  originJobId: string | null;
+  parentWorkflowId: string;
+  workflowDimension: string;
+  workflowId: string;
+  workflowTopic: string;
+  constructor(params: {
+    arguments: string[],
+    activityName: string,
+    backoffCoefficient?: number,
+    index: number,
+    maximumAttempts?: number,
+    maximumInterval?: number,
+    originJobId: string | null,
+    parentWorkflowId: string,
+    workflowDimension: string,
+    workflowId: string,
+    workflowTopic: string,
+  }) {
+    super(`Durable Proxy Activity Error [${params.parentWorkflowId}] => [${params.workflowId}]`);
+    this.arguments = params.arguments;
+    this.workflowId = params.workflowId;
+    this.workflowTopic = params.workflowTopic;
+    this.parentWorkflowId = params.parentWorkflowId;
+    this.originJobId = params.originJobId;
+    this.index = params.index;
+    this.activityName = params.activityName;
+    this.workflowDimension = params.workflowDimension;
+    this.backoffCoefficient = params.backoffCoefficient;
+    this.maximumAttempts = params.maximumAttempts;
+    this.maximumInterval = params.maximumInterval;
+    this.code = HMSH_CODE_DURABLE_PROXY;
+  }
+}
+
+class DurableChildError extends Error {
+  await: boolean;
+  arguments: string[];
+  backoffCoefficient: number;
+  code: number;
+  workflowDimension: string;
+  index: number;
+  maximumAttempts: number;
+  maximumInterval: number;
+  originJobId: string | null;
+  parentWorkflowId: string;
+  workflowId: string;
+  workflowTopic: string;
+  constructor(params: {
+    arguments: string[],
+    await?: boolean,
+    backoffCoefficient?: number,
+    index: number,
+    maximumAttempts?: number,
+    maximumInterval?: number,
+    originJobId: string | null,
+    parentWorkflowId: string,
+    workflowDimension: string,
+    workflowId: string,
+    workflowTopic: string,
+  }) {
+    super(`Durable Child Error [${params.parentWorkflowId}] => [${params.workflowId}]`);
+    this.arguments = params.arguments;
+    this.workflowId = params.workflowId;
+    this.workflowTopic = params.workflowTopic;
+    this.parentWorkflowId = params.parentWorkflowId;
+    this.originJobId = params.originJobId;
+    this.index = params.index;
+    this.workflowDimension = params.workflowDimension;
+    this.code = HMSH_CODE_DURABLE_CHILD;
+    this.await = params.await;
+    this.backoffCoefficient = params.backoffCoefficient;
+    this.maximumAttempts = params.maximumAttempts;
+    this.maximumInterval = params.maximumInterval;
+  }
+}
+
+class DurableWaitForAllError extends Error {
+  items: any[];
+  code: number;
+  workflowDimension: string;
+  size: number;
+  index: number;
+  originJobId: string | null;
+  parentWorkflowId: string;
+  workflowId: string;
+  workflowTopic: string;
+  constructor(params: {
+    items: string[],
+    workflowId: string,
+    workflowTopic: string,
+    parentWorkflowId: string,
+    originJobId: string | null,
+    size: number,
+    index: number,
+    workflowDimension: string
+  }) {
+    super(`Durable Wait for All Error [${params.parentWorkflowId}] => [${params.workflowId}]`);
+    this.items = params.items;
+    this.size = params.size;
+    this.workflowId = params.workflowId;
+    this.workflowTopic = params.workflowTopic;
+    this.parentWorkflowId = params.parentWorkflowId;
+    this.originJobId = params.originJobId;
+    this.index = params.index;
+    this.workflowDimension = params.workflowDimension;
+    this.code = HMSH_CODE_DURABLE_ALL;
   }
 }
 
-class DurableSleepForError extends Error {
+class DurableSleepError extends Error {
+  workflowId: string;
   code: number;
   duration: number; //seconds
-  index: number;    //execution order in the workflow
-  dimension: string; //hook dimension (e.g., ',0,1,0') (uses empty string for `null`)
-  constructor(message: string, duration: number, index: number, dimension: string) {
-    super(message);
-    this.duration = duration;
-    this.index = index;
-    this.dimension = dimension;
-    this.code = HMSH_CODE_DURABLE_SLEEPFOR;
+  index: number;
+  workflowDimension: string; //empty string for null
+  constructor(params: {
+    duration: number,
+    index: number,
+    workflowDimension: string,
+    workflowId: string,
+  }) {
+    super(`Durable Sleep Error [${params.workflowId}]`);
+    this.duration = params.duration;
+    this.workflowId = params.workflowId;
+    this.index = params.index;
+    this.workflowDimension = params.workflowDimension;
+    this.code = HMSH_CODE_DURABLE_SLEEP;
   }
 }
+
 class DurableTimeoutError extends Error {
   code: number;
-  constructor(message: string) {
+  constructor(message: string, stack?: string) {
     super(message);
+    if (this.stack) {
+      this.stack = stack;
+    }
     this.code = HMSH_CODE_DURABLE_TIMEOUT;
   }
 }
 class DurableMaxedError extends Error {
   code: number;
-  constructor(message: string) {
+  constructor(message: string, stackTrace?: string) {
     super(message);
+    if (stackTrace) {
+      this.stack = stackTrace;
+    }
     this.code = HMSH_CODE_DURABLE_MAXED;
   }
 }
 class DurableFatalError extends Error {
   code: number;
-  constructor(message: string) {
+  constructor(message: string, stackTrace?: string) {
     super(message);
+    if (stackTrace) {
+      this.stack = stackTrace;
+    }
     this.code = HMSH_CODE_DURABLE_FATAL;
   }
 }
 class DurableRetryError extends Error {
   code: number;
-  constructor(message: string) {
+  constructor(message: string, stackTrace?: string) {
     super(message);
+    if (stackTrace) {
+      this.stack = stackTrace;
+    }
     this.code = HMSH_CODE_DURABLE_RETRYABLE;
   }
 }
@@ -100,8 +238,10 @@ class RegisterTimeoutError extends Error {
 }
 
 class DuplicateJobError extends Error {
+  jobId: string;
   constructor(jobId: string) {
     super("Duplicate job");
+    this.jobId = jobId;
     this.message = `Duplicate job: ${jobId}`;
   }
 }
@@ -157,13 +297,15 @@ class CollationError extends Error {
 
 export {
   CollationError,
+  DurableChildError,
   DurableFatalError,
-  DurableIncompleteSignalError,
   DurableMaxedError,
+  DurableProxyError,
   DurableRetryError,
-  DurableSleepForError,
+  DurableSleepError,
   DurableTimeoutError,
-  DurableWaitForSignalError,
+  DurableWaitForAllError,
+  DurableWaitForError,
   DuplicateJobError,
   ExecActivityError,
   GenerationalError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/hotmesh",
-  "version": "0.0.51",
+  "version": "0.0.53",
   "description": "Unbreakable Workflows",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
@@ -21,13 +21,16 @@
     "start": "ts-node src/index.ts",
     "test": "NODE_ENV=test jest --detectOpenHandles --forceExit --verbose",
     "test:hmsh": "NODE_ENV=test jest ./tests/functional/index.test.ts --detectOpenHandles --verbose",
+    "test:pipe": "NODE_ENV=test jest ./tests/unit/services/pipe/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:compile": "NODE_ENV=test jest ./tests/functional/compile/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:cycle": "NODE_ENV=test jest ./tests/functional/cycle/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:trigger": "NODE_ENV=test jest ./tests/unit/services/activities/trigger.test.ts --detectOpenHandles --forceExit --verbose",
     "test:connect": "NODE_ENV=test jest ./tests/unit/services/connector/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:connect:redis": "NODE_ENV=test jest ./tests/unit/services/connector/clients/redis.test.ts --detectOpenHandles --forceExit --verbose",
     "test:connect:ioredis": "NODE_ENV=test jest ./tests/unit/services/connector/clients/ioredis.test.ts --detectOpenHandles --forceExit --verbose",
+    "test:functional": "NODE_ENV=test jest ./tests/functional/*/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:emit": "NODE_ENV=test jest ./tests/functional/emit/index.test.ts --detectOpenHandles --forceExit --verbose",
+    "test:reentrant": "NODE_ENV=test jest ./tests/functional/reentrant/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:await": "NODE_ENV=test jest ./tests/functional/awaiter/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:hook": "NODE_ENV=test jest ./tests/functional/hook/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:signal": "NODE_ENV=test jest ./tests/functional/signal/index.test.ts --detectOpenHandles --forceExit --verbose",
@@ -46,13 +49,15 @@
     "test:sub:redis": "NODE_ENV=test jest ./tests/functional/sub/clients/redis.test.ts --detectOpenHandles --forceExit --verbose",
     "test:sub:ioredis": "NODE_ENV=test jest ./tests/functional/sub/clients/ioredis.test.ts --detectOpenHandles --forceExit --verbose",
     "test:durable": "NODE_ENV=test jest ./tests/durable/*/index.test.ts --detectOpenHandles --forceExit --verbose",
-    "test:durable:meshos": "NODE_ENV=test jest ./tests/durable/meshos/index.test.ts --detectOpenHandles --forceExit --verbose",
+    "test:durable:basic": "NODE_ENV=test jest ./tests/durable/basic/index.test.ts --detectOpenHandles --forceExit --verbose",
+    "test:durable:collision": "NODE_ENV=test jest ./tests/durable/collision/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:durable:hello": "NODE_ENV=test jest ./tests/durable/helloworld/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:durable:interrupt": "NODE_ENV=test jest ./tests/durable/interrupt/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:durable:goodbye": "NODE_ENV=test jest ./tests/durable/goodbye/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:durable:hook": "NODE_ENV=test jest ./tests/durable/hook/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:durable:retry": "NODE_ENV=test jest ./tests/durable/retry/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:durable:fatal": "NODE_ENV=test jest ./tests/durable/fatal/index.test.ts --detectOpenHandles --forceExit --verbose",
+    "test:durable:unknown": "NODE_ENV=test jest ./tests/durable/unknown/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:durable:sleep": "NODE_ENV=test jest ./tests/durable/sleep/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:durable:signal": "NODE_ENV=test jest ./tests/durable/signal/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:durable:loopactivity": "NODE_ENV=test jest ./tests/durable/loopactivity/index.test.ts --detectOpenHandles --forceExit --verbose",