@hotmeshio/hotmesh 0.3.29 → 0.3.31

package/build/types/pipe.d.ts

@@ -1,17 +1,82 @@
+/**
+ * Represents a single cell value in a pipeline row
+ * If the value is a string, the value will be a literal OR mapping expression
+ */
 type PipeItem = string | boolean | number | null | object;
+/**
+ * Array of `PipeItem` types.
+ */
 type PipeItems = PipeItem[];
+/**
+ * Represents a new nested context in the pipeline.
+ * As the structure is recursive, the nested pipe may contain an
+ * array of `PipeItem[]`, `PipeObject`, OR `ReduceObject` items.
+ */
 type PipeObject = {
     '@pipe': Array<PipeItem[] | PipeObject | ReduceObject>;
 };
+/**
+ * Reduce is similar to Pipe in that it represents a new context
+ * and may include an array of `PipeItem[]`, `PipeObject`, or `ReduceObject`.
+ * But it also iterates and produces output. The context variables,
+ * `$input`, `$output`, `$item`, `$key`, and `$index` are available.
+ * @example
+ *
+ * // Example of a reduce expression. The optional object is empty and
+ * // serves as the $output during iteration. The last step in the iteration
+ * // sets $output. if ther are no more iterations, the $output is returned
+ * // and provided to the next step in the pipeline.
+ *
+ * // If data is:
+ * // { response: ['a', 'b', 'c'] }
+ *
+ * // The reduced/transformed expression will be:
+ * // { 'a': 0, 'b': 1, 'c': 2 }
+ *
+ * // Arrays and objects may be iterated over and transformed.
+ *
+ * //YAML
+ * '@pipe':
+ *   - ['{data.response}', {}]
+ *   - '@reduce':
+ *       - '@pipe':
+ *           - ['{$output}']
+ *       - '@pipe':
+ *           - ['{$item}']
+ *       - '@pipe':
+ *           - ['{$index}']
+ *       - ['{@object.set}']
+ */
 type ReduceObject = {
     '@reduce': Array<PipeItem[] | PipeObject | ReduceObject>;
 };
+/**
+ * Represents a sequence in the pipeline that can include arrays of `PipeItem`, `PipeObject`, or `ReduceObject`.
+ */
 type Pipe = (PipeItem[] | PipeObject | ReduceObject)[];
+/**
+ * Defines the context of a pipeline operation.
+ */
 type PipeContext = {
+    /**
+     * Input of the current iteration.
+     */
     $input: unknown[];
+    /**
+     * Output of the current iteration and the final output for the reducer.
+     */
     $output: unknown;
+    /**
+     * Target item in the iterator.
+     */
     $item: unknown;
+    /**
+     * Array index as string or object key.
+     */
     $key: string;
+    /**
+     * Numeric index of the iterator.
+     */
     $index: number;
 };
 export { Pipe, PipeContext, PipeItem, PipeItems, PipeObject, ReduceObject };

package/build/types/provider.d.ts

@@ -1,29 +1,66 @@
 import { KeyStoreParams } from '../modules/key';
 import { StringAnyType } from './serializer';
+/**
+ * Generic type for provider class
+ */
 export interface ProviderClass {
     [key: string]: any;
 }
+/**
+ * Generic type for provider options
+ */
 export interface ProviderOptions {
     [key: string]: any;
 }
 export type Providers = 'redis' | 'nats' | 'postgres' | 'ioredis';
+/**
+ * A provider transaction is a set of operations that are executed
+ * atomically by the provider. The transaction is created by calling
+ * the `transact` method on the provider. The transaction object
+ * contains methods specific to the provider allowing it to optionally
+ * choose to execute a single command or collect all commands and
+ * execute as a single transaction.
+ */
 export interface ProviderTransaction {
     exec(): Promise<any>;
     [key: string]: ((...args: any[]) => Promise<any>) | undefined | any;
 }
+/**
+ * A provider native client is the raw client object provided by the
+ * connecter service. This object is passed to the ProviderClient
+ * (which wraps it), providing a standardized interface for all
+ * providers.
+ */
 export interface ProviderNativeClient {
     [key: string]: any;
 }
+/**
+ * Wrapped provider native client object that standardizes the
+ * interface for all providers.
+ */
 export interface ProviderClient {
+    /** The provider-specific transaction object */
     transact(): ProviderTransaction;
+    /** Mint a provider-specific key */
     mintKey(type: KeyType, params: KeyStoreParams): string;
+    /** The provider-specific client object */
     [key: string]: any;
 }
+/**
+ * an array of outputs generic to all providers
+ * e.g., [3, 2, '0']
+ */
 export type TransactionResultList = (string | number)[];
 export type ProviderConfig = {
     class: any;
     options: StringAnyType;
     provider?: string;
+    /**
+     * If provided and if true, the engine router instance will
+     * be initialized as a readonly instance and will not consume
+     * messages from the stream channel. An engine in readonly mode
+     * can still read/write to the store and can still pub/sub events.
+     */
     readonly?: boolean;
 };
 export type ProvidersConfig = {
@@ -32,6 +69,12 @@ export type ProvidersConfig = {
     stream: ProviderConfig;
     pub?: ProviderConfig;
     search?: ProviderConfig;
+    /**
+     * If provided and if true, the engine router instance will
+     * be initialized as a readonly instance and will not consume
+     * messages from the stream channel. An engine in readonly mode
+     * can still read/write to the store and can still pub/sub events.
+     */
     readonly?: boolean;
 };
 export interface SetOptions {

package/build/types/quorum.d.ts

@@ -16,6 +16,7 @@ interface NetworkStat {
     tx_sec: number;
     ms: number;
 }
+/** reveals: memory, cpu, network */
 export interface SystemHealth {
     TotalMemoryGB: string;
     FreeMemoryGB: string;
@@ -24,10 +25,15 @@ export interface SystemHealth {
     NetworkStats: NetworkStat[];
 }
 export type ThrottleOptions = {
+    /** target an engine OR worker by GUID */
     guid?: string;
+    /** target a worker quorum */
     topic?: string;
+    /** entity/noun */
     entity?: string;
+    /** in milliseconds; set to -1 for indefinite throttle */
     throttle: number;
+    /** namespace */
     namespace?: string;
 };
 export interface QuorumProfile {
@@ -121,5 +127,11 @@ export type RollCallOptions = {
 export type SubscriptionOptions = {
     namespace?: string;
 };
+/**
+ * The types in this file are used to define those messages that are sent
+ * to hotmesh client instances when a new version is about to be activated.
+ * These messages serve to coordinate the cache invalidation and switch-over
+ * to the new version without any downtime and a coordinating parent server.
+ */
 export type QuorumMessage = PingMessage | PongMessage | ActivateMessage | WorkMessage | JobMessage | ThrottleMessage | RollCallMessage | CronMessage | UserMessage;
 export {};

package/build/types/redis.d.ts

@@ -2,6 +2,9 @@
 import { ProviderClient, ProviderConfig, ProviderTransaction } from './provider';
 import { StringStringType } from './serializer';
 import { ReclaimedMessageType } from './stream';
+/**
+ * Redis types
+ */
 interface ConnectionOptions {
     host?: string;
     port?: number;
@@ -150,6 +153,9 @@ interface RedisRedisClientType extends ProviderClient {
 interface RedisRedisClassType {
     createClient(options: RedisRedisClientOptions): Partial<RedisRedisClientType>;
 }
+/**
+ * IORedis types
+ */
 interface IORedisClientOptions {
     port?: number;
     host?: string;

package/build/types/stream.d.ts

@@ -1,20 +1,39 @@
 import { ProviderTransaction } from './provider';
+/** Represents a policy for retrying stream operations based on error codes */
 export interface StreamRetryPolicy {
+    /**
+     * 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 {
@@ -28,50 +47,91 @@ 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 type StreamDataResponse = StreamData;
 export declare enum StreamRole {
     WORKER = "worker",
     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 RouterConfig = {
+    /** 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;
+    /** Default throttle (read from KeyType.THROTTLE_RATE) */
     throttle: number;
+    /** 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;
+    /** if true, will not process stream messages; default true */
     readonly?: boolean;
 };
 export type StreamProviderType = 'redis' | 'ioredis' | 'postgres' | 'nats' | 'sqs';
@@ -134,6 +194,11 @@ export interface StreamStats {
     lastErrorMessage?: string;
     [key: string]: any;
 }
+/**
+ * When publishing a message to the stream, the configuration
+ * can include a transaction object to execute the operation
+ * atomically.
+ */
 export interface PublishMessageConfig {
     transaction?: ProviderTransaction;
 }

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

@@ -2,7 +2,13 @@ import { HotMesh } from './services/hotmesh';
 import { HotMeshConfig } from './types/hotmesh';
 import { MeshCall } from './services/meshcall';
 import { MeshFlow } from './services/meshflow';
+import { ClientService as Client } from './services/meshflow/client';
+import { ConnectionService as Connection } from './services/meshflow/connection';
+import { Search } from './services/meshflow/search';
+import { WorkerService as Worker } from './services/meshflow/worker';
+import { WorkflowService as workflow } from './services/meshflow/workflow';
 import { WorkflowHandleService as WorkflowHandle } from './services/meshflow/handle';
+import { proxyActivities } from './services/meshflow/workflow/proxyActivities';
 import { MeshData } from './services/meshdata';
 import { MeshOS } from './services/meshos';
 import * as Errors from './modules/errors';
@@ -15,7 +21,7 @@ import { RedisConnection as ConnectorIORedis } from './services/connector/provid
 import { RedisConnection as ConnectorRedis } from './services/connector/providers/redis';
 import { NatsConnection as ConnectorNATS } from './services/connector/providers/nats';
 
-const { Client, Connection, Search, Worker, workflow } = MeshFlow;
+//const { Client, Connection, Search, Worker, workflow } = MeshFlow;
 
 export {
   //Provider Connectors
@@ -36,6 +42,7 @@ export {
   //MeshFlow Submodules
   Client,
   Connection,
+  proxyActivities,
   Search,
   Worker,
   workflow,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/hotmesh",
-  "version": "0.3.29",
+  "version": "0.3.31",
   "description": "Serverless Workflow",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
@@ -49,12 +49,12 @@
     "test:parallel": "NODE_ENV=test jest ./tests/functional/parallel/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:pipe": "NODE_ENV=test jest ./tests/unit/services/pipe/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:quorum": "HMSH_IS_CLUSTER=true NODE_ENV=test jest ./tests/functional/quorum/*.test.ts --detectOpenHandles --forceExit --verbose",
-    "test:reclaim": "NODE_ENV=test jest ./tests/functional/reclaim/index.test.ts --detectOpenHandles --forceExit --verbose",
+    "test:reclaim": "NODE_ENV=test jest ./tests/functional/reclaim/*.test.ts --detectOpenHandles --forceExit --verbose",
     "test:redeploy": "NODE_ENV=test jest ./tests/functional/redeploy/*.test.ts --detectOpenHandles --forceExit --verbose",
     "test:reporter": "NODE_ENV=test jest ./tests/unit/services/reporter/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:reentrant": "NODE_ENV=test jest ./tests/functional/reentrant/*.test.ts --detectOpenHandles --forceExit --verbose",
     "test:retry": "NODE_ENV=test jest ./tests/functional/retry/*.test.ts --detectOpenHandles --forceExit --verbose",
-    "test:sequence": "NODE_ENV=test HMSH_LOGLEVEL=debug jest ./tests/functional/sequence/*.test.ts --detectOpenHandles --forceExit --verbose",
+    "test:sequence": "NODE_ENV=test HMSH_LOGLEVEL=info jest ./tests/functional/sequence/*.test.ts --detectOpenHandles --forceExit --verbose",
     "test:signal": "NODE_ENV=test jest ./tests/functional/signal/*.test.ts --detectOpenHandles --forceExit --verbose",
     "test:status": "NODE_ENV=test jest ./tests/functional/status/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:providers": "NODE_ENV=test jest ./tests/functional/*/providers/*/*.test.ts --detectOpenHandles --forceExit --verbose",
@@ -71,7 +71,7 @@
     "test:sub:nats": "NODE_ENV=test jest ./tests/functional/sub/providers/nats/nats.test.ts --detectOpenHandles --forceExit --verbose",
     "test:trigger": "NODE_ENV=test jest ./tests/unit/services/activities/trigger.test.ts --detectOpenHandles --forceExit --verbose",
     "test:meshdata": "NODE_ENV=test jest ./tests/meshdata/*.test.ts --forceExit --verbose --detectOpenHandles",
-    "test:meshos": "HMSH_LOGLEVEL=debug NODE_ENV=test HMSH_IS_CLUSTER=true jest ./tests/meshos/*.test.ts --forceExit --verbose --detectOpenHandles",
+    "test:meshos": "HMSH_LOGLEVEL=info NODE_ENV=test HMSH_IS_CLUSTER=true jest ./tests/meshos/*.test.ts --forceExit --verbose --detectOpenHandles",
     "test:meshcall": "NODE_ENV=test jest ./tests/meshcall/*.test.ts --forceExit --verbose --detectOpenHandles",
     "test:unit": "NODE_ENV=test jest ./tests/unit/*/*/index.test.ts --detectOpenHandles --forceExit --verbose"
   },
@@ -80,6 +80,7 @@
     "Serverless Workflow",
     "Durable Workflow",
     "Operational Data",
+    "Saasless Apps",
     "Service Mesh",
     "HotMesh",
     "Postgres",
@@ -117,6 +118,7 @@
     "pg": "^8.10.0",
     "redis": "^4.6.13",
     "rimraf": "^4.4.1",
+    "terser": "^5.37.0",
     "ts-jest": "^29.0.5",
     "ts-node": "^10.9.1",
     "ts-node-dev": "^2.0.0",

package/types/manifest.ts

@@ -24,14 +24,14 @@ export type EntityInstanceTypes = MeshOS;
 
 export type SubclassType<T extends MeshOS = MeshOS> = new (...args: any[]) => T;
 export type Entity = {
-  name: string;                 //can be set via static config
+  name: string; //can be set via static config
   label: string;
   /**
    * A more-specific value for workers when targeting version-specifc
    * or priority-specific task queues.
    * @default default
    */
-  taskQueue?: string;           //can be set via static config
+  taskQueue?: string; //can be set via static config
   schema: WorkflowSearchSchema; //can be st via static config
   class: SubclassType;
 };

package/types/meshcall.ts

@@ -150,8 +150,7 @@ interface MeshCallCronParams {
    */
   guid?: string;
   /**
-   * Namespace for grouping common cron functions. The cron job keys in Redis
-   * will be prefixed with this namespace. (e.g. `hmsh:[namespace]:j:*`)
+   * Namespace for grouping common cron functions. (e.g. `hmsh:[namespace]:j:*`)
    */
   namespace?: string;
   /**

package/types/meshdata.ts

@@ -177,7 +177,7 @@ export type HookInput = {
 
 export type MeshDataWorkflowOptions = {
   /**
-   * The app deployment namespace; how it appears in redis (e.g., 'meshflow')
+   * The app deployment namespace
    */
   namespace?: string;