@hotmeshio/hotmesh 0.0.52 → 0.0.53

package/build/types/durable.d.ts

@@ -1,13 +1,45 @@
 import { LogLevel } from './logger';
 import { RedisClass, RedisOptions } from './redis';
 import { StringStringType } from './serializer';
+import { StreamData, StreamError } from './stream';
+/**
+ * Type definition for workflow configuration.
+ */
 type WorkflowConfig = {
+    /**
+     * Backoff coefficient for retry mechanism.
+     * @default 10 (HMSH_DURABLE_EXP_BACKOFF)
+     */
     backoffCoefficient?: number;
+    /**
+     * Maximum number of attempts for retries.
+     * @default 5 (HMSH_DURABLE_MAX_ATTEMPTS)
+     */
     maximumAttempts?: number;
+    /**
+     * Maximum interval between retries.
+     * @default 120s (HMSH_DURABLE_MAX_INTERVAL)
+     */
     maximumInterval?: string;
-    initialInterval?: string;
+    /**
+     * Whether to throw an error on final failure after retries are exhausted
+     * or return the error object as a standard response containing error-related
+     * fields like `stack`, `code`, `message`.
+     * @default true
+     */
+    throwOnError?: boolean;
 };
 type WorkflowContext = {
+    /**
+     * can the workflow be retried if an error occurs
+     */
+    canRetry: boolean;
+    COUNTER: {
+        /**
+         * the reentrant semaphore parent counter object for object reference during increment
+         */
+        counter: number;
+    };
     /**
      * the reentrant semaphore, incremented in real-time as idempotent statements are re-traversed upon reentry. Indicates the current semaphore count.
      */
@@ -44,45 +76,129 @@ type WorkflowContext = {
      * the open telemetry span context for the workflow, used for logging and tracing. If a sink is enabled, this will be sent to the sink.
      */
     workflowSpan: string;
+    /**
+     * the native HotMesh message that encapsulates the arguments, metadata, and raw data for the workflow
+     */
+    raw: StreamData;
 };
 type WorkflowSearchOptions = {
+    /** FT index name (myapp:myindex) */
     index?: string;
+    /** FT prefixes (['myapp:myindex:prefix1', 'myapp:myindex:prefix2']) */
     prefix?: string[];
+    /**
+     * Schema mapping each field to a type with an optional sortable flag
+     */
     schema?: Record<string, {
         type: 'TEXT' | 'NUMERIC' | 'TAG';
         sortable?: boolean;
     }>;
+    /** Additional data as a key-value record */
     data?: Record<string, string>;
 };
 type WorkflowOptions = {
+    /**
+     * the namespace for the workflow; `durable` is the default namespace if not provided
+     */
     namespace?: string;
+    /**
+     * the task queue for the workflow; optional if entity is provided
+     */
     taskQueue?: string;
+    /**
+     * input arguments to pass in
+     */
     args: any[];
+    /**
+     * the job id
+     */
     workflowId?: string;
+    /**
+     * if invoking a workflow, passing 'entity' will apply the value as the workflowName, taskQueue, and prefix, ensuring the FT.SEARCH index is properly scoped. This is a convenience method but limits options.
+     */
     entity?: string;
+    /**
+     * the name of the user's workflow function; optional if 'entity' is provided
+     */
     workflowName?: string;
+    /**
+     * the parent workflow id; adjacent ancestor ID
+     */
     parentWorkflowId?: string;
+    /**
+     * the entry point workflow id
+     */
     originJobId?: string;
+    /**
+     * OpenTelemetry trace context for the workflow
+     */
     workflowTrace?: string;
+    /**
+     * OpenTelemetry span context for the workflow
+     */
     workflowSpan?: string;
+    /**
+     * the full-text-search (RediSearch) options for the workflow
+     */
     search?: WorkflowSearchOptions;
+    /**
+     * the workflow configuration object
+     */
     config?: WorkflowConfig;
+    /**
+     * sets the number of seconds a workflow may exist after completion. As the process engine is an in-memory cache, the default policy is to expire and scrub the job hash as soon as it completes.
+     */
     expire?: number;
+    /**
+     * default is true; if false, will not await the execution
+     */
+    await?: boolean;
 };
+/**
+ * Options for setting up a hook.
+ * 'durable' is the default namespace if not provided; similar to setting `appid` in the YAML
+ */
 type HookOptions = {
+    /** Optional namespace under which the hook function will be grouped */
     namespace?: string;
+    /** Optional task queue, needed unless 'entity' is provided */
     taskQueue?: string;
+    /** Input arguments to pass into the hook */
     args: any[];
+    /**
+     * Optional entity name. If provided, applies as the workflowName,
+     * taskQueue, and prefix. This scopes the FT.SEARCH index appropriately.
+     * This is a convenience method but limits options.
+     */
     entity?: string;
+    /** Execution ID, also known as the job ID to hook into */
     workflowId?: string;
+    /** The name of the user's hook function */
     workflowName?: string;
+    /** Bind additional search terms immediately before hook reentry */
     search?: WorkflowSearchOptions;
+    /** Hook function constraints (backoffCoefficient, maximumAttempts, maximumInterval) */
     config?: WorkflowConfig;
 };
+/**
+ * Options for sending signals in a workflow.
+ */
 type SignalOptions = {
+    /**
+     * Task queue associated with the workflow
+     */
     taskQueue: string;
+    /**
+     * Input data for the signal (any serializable object)
+     */
     data: Record<string, any>;
+    /**
+     * Execution ID, also known as the job ID
+     */
     workflowId: string;
+    /**
+     * Optional name of the user's workflow function
+     */
     workflowName?: string;
 };
 type ActivityWorkflowDataType = {
@@ -97,17 +213,7 @@ type WorkflowDataType = {
     workflowTopic: string;
     workflowDimension?: string;
     originJobId?: string;
-};
-type MeshOSClassConfig = {
-    namespace: string;
-    taskQueue: string;
-    redisOptions: RedisOptions;
-    redisClass: RedisClass;
-};
-type MeshOSConfig = {
-    id?: string;
-    await?: boolean;
-    taskQueue?: string;
+    canRetry?: boolean;
 };
 type ConnectionConfig = {
     class: RedisClass;
@@ -121,11 +227,20 @@ type Registry = {
     [key: string]: Function;
 };
 type WorkerConfig = {
+    /** Connection configuration for the worker */
     connection: Connection;
+    /**
+     * Namespace used in the app configuration, denoted as `appid` in the YAML (e.g., 'durable')
+     * @default durable
+     */
     namespace?: string;
+    /** Task queue name, denoted as `subscribes` in the YAML (e.g., 'hello-world') */
     taskQueue: string;
+    /** Target function or a record type with a name (string) and reference function */
     workflow: Function | Record<string | symbol, Function>;
+    /** Additional options for configuring the worker */
     options?: WorkerOptions;
+    /** Search options for workflow execution details */
     search?: WorkflowSearchOptions;
 };
 type FindWhereQuery = {
@@ -150,25 +265,15 @@ type FindWhereOptions = {
         size: number;
     };
 };
-type MeshOSOptions = {
-    name: string;
-    options: WorkerOptions;
-};
-type MeshOSActivityOptions = {
-    name: string;
-    options: ActivityConfig;
-};
-type MeshOSWorkerOptions = {
-    taskQueue?: string;
-    allowList?: Array<MeshOSOptions | string>;
-    logLevel?: LogLevel;
-    maxSystemRetries?: number;
-    backoffCoefficient?: number;
-};
 type WorkerOptions = {
+    /** Log level: debug, info, warn, error */
     logLevel?: LogLevel;
-    maxSystemRetries?: number;
+    /** Maximum number of attempts, default 5 (HMSH_DURABLE_MAX_ATTEMPTS) */
+    maximumAttempts?: number;
+    /** Backoff coefficient for retry logic, default 10 (HMSH_DURABLE_EXP_BACKOFF) */
     backoffCoefficient?: number;
+    /** Maximum interval between retries, default 120s (HMSH_DURABLE_MAX_INTERVAL) */
+    maximumInterval?: string;
 };
 type ContextType = {
     workflowId: string;
@@ -178,14 +283,44 @@ type FunctionSignature<T> = T extends (...args: infer A) => infer R ? (...args:
 type ProxyType<ACT> = {
     [K in keyof ACT]: FunctionSignature<ACT[K]>;
 };
+/**
+ * Configuration settings for activities within a workflow.
+ */
 type ActivityConfig = {
+    /** Start to close timeout for the activity; not yet implemented */
     startToCloseTimeout?: string;
+    /** Configuration for specific activities, type not yet specified */
     activities?: any;
+    /** Retry policy configuration for activities */
     retryPolicy?: {
-        initialInterval: string;
-        maximumAttempts: number;
-        backoffCoefficient: number;
-        maximumInterval: string;
+        /** Maximum number of retry attempts, default is 5 (HMSH_DURABLE_MAX_ATTEMPTS) */
+        maximumAttempts?: number;
+        /** Factor by which the retry timeout increases, default is 10 (HMSH_DURABLE_MAX_INTERVAL) */
+        backoffCoefficient?: number;
+        /** Maximum interval between retries, default is '120s' (HMSH_DURABLE_EXP_BACKOFF) */
+        maximumInterval?: string;
+        /** Whether to throw an error on failure, default is true */
+        throwOnError?: boolean;
     };
 };
-export { ActivityConfig, ActivityWorkflowDataType, ClientConfig, ContextType, ConnectionConfig, Connection, ProxyType, Registry, SignalOptions, FindOptions, FindWhereOptions, FindWhereQuery, HookOptions, MeshOSActivityOptions, MeshOSWorkerOptions, MeshOSClassConfig, MeshOSConfig, MeshOSOptions, WorkerConfig, WorkflowConfig, WorkerOptions, WorkflowSearchOptions, WorkflowDataType, WorkflowOptions, WorkflowContext, };
+/**
+ * The proxy response object returned from the activity proxy flow
+ */
+type ProxyResponseType<T> = {
+    data?: T;
+    $error?: StreamError;
+    done?: boolean;
+    jc: string;
+    ju: string;
+};
+/**
+ * The child flow response object returned from the  main flow during recursion
+ */
+type ChildResponseType<T> = {
+    data?: T;
+    $error?: StreamError;
+    done?: boolean;
+    jc: string;
+    ju: string;
+};
+export { ActivityConfig, ActivityWorkflowDataType, ChildResponseType, ClientConfig, ContextType, ConnectionConfig, Connection, ProxyResponseType, ProxyType, Registry, SignalOptions, FindOptions, FindWhereOptions, FindWhereQuery, HookOptions, WorkerConfig, WorkflowConfig, WorkerOptions, WorkflowSearchOptions, WorkflowDataType, WorkflowOptions, WorkflowContext, };

package/build/types/exporter.d.ts

@@ -37,14 +37,36 @@ export interface ExportTransitions {
 export interface ExportCycles {
     [key: string]: string[];
 }
+export type IdemParts = {
+    index: number;
+    secondary?: number;
+    dimension?: string;
+};
+export type IdemType = {
+    key: string;
+    value: string;
+    parts: IdemParts;
+};
+export interface TimelineEntry {
+    activity: string;
+    dimensions: string;
+    created: string;
+    updated: string;
+}
+export interface TimestampParts {
+    activity: string;
+    dimensions: string;
+    created: string;
+    updated: string;
+}
 export interface DurableJobExport {
     data: StringAnyType;
-    dependencies: DependencyExport[];
+    dependencies?: Record<string, any>[];
     state: StringAnyType;
     status: string;
-    timeline: JobTimeline[];
-    transitions: ExportTransitions;
-    cycles: ExportCycles;
+    timeline?: JobTimeline[];
+    idempotents: IdemType[];
+    replay: TimestampParts[];
 }
 export interface JobExport {
     dependencies: DependencyExport[];

package/build/types/index.d.ts

@@ -3,14 +3,14 @@ export { App, AppVID, AppTransitions, AppSubscriptions } from './app';
 export { AsyncSignal } from './async';
 export { CacheMode } from './cache';
 export { CollationFaultType, CollationStage } from './collator';
-export { ActivityConfig, ActivityWorkflowDataType, ClientConfig, ContextType, ConnectionConfig, Connection, ProxyType, Registry, SignalOptions, FindOptions, FindWhereOptions, FindWhereQuery, HookOptions, MeshOSActivityOptions, MeshOSWorkerOptions, MeshOSClassConfig, MeshOSConfig, MeshOSOptions, WorkflowConfig, WorkerConfig, WorkerOptions, WorkflowContext, WorkflowSearchOptions, WorkflowDataType, WorkflowOptions, } from './durable';
+export { ActivityConfig, ActivityWorkflowDataType, ChildResponseType, ClientConfig, ContextType, ConnectionConfig, Connection, ProxyResponseType, ProxyType, Registry, SignalOptions, FindOptions, FindWhereOptions, FindWhereQuery, HookOptions, WorkflowConfig, WorkerConfig, WorkerOptions, WorkflowContext, WorkflowSearchOptions, WorkflowDataType, WorkflowOptions, } from './durable';
 export { ActivityAction, DependencyExport, DurableJobExport, ExportCycles, ExportItem, ExportOptions, ExportTransitions, JobAction, JobExport, JobActionExport, JobTimeline } from './exporter';
 export { HookCondition, HookConditions, HookGate, HookInterface, HookRule, HookRules, HookSignal } from './hook';
 export { RedisClientType as IORedisClientType, RedisMultiType as IORedisMultiType } from './ioredisclient';
 export { ILogger } from './logger';
 export { JobData, JobsData, JobMetadata, JobOutput, JobState, JobStatus, PartialJobState } from './job';
 export { MappingStatements } from './map';
-export { Pipe, PipeItem, PipeItems } from './pipe';
+export { Pipe, PipeContext, PipeItem, PipeItems, PipeObject, ReduceObject } from './pipe';
 export { HotMesh, HotMeshApp, HotMeshApps, HotMeshConfig, HotMeshEngine, RedisConfig, HotMeshGraph, HotMeshManifest, HotMeshSettings, HotMeshWorker, KeyStoreParams, KeyType } from './hotmesh';
 export { ActivateMessage, CronMessage, JobMessage, JobMessageCallback, PingMessage, PongMessage, QuorumMessage, QuorumMessageCallback, QuorumProfile, RollCallMessage, SubscriptionCallback, SystemHealth, ThrottleMessage, ThrottleOptions, WorkMessage } from './quorum';
 export { MultiResponseFlags, RedisClient, RedisMulti } from './redis';

package/build/types/job.d.ts

@@ -5,32 +5,59 @@ type ActivityData = {
     metadata?: Record<string, unknown>;
 };
 type JobMetadata = {
+    /** job_key */
     key?: string;
+    /** system assigned guid that corresponds to the transition message guid that spawned reentry */
     guid?: string;
+    /** system assigned guid; ensured created/deleted/created jobs are unique */
     gid: string;
+    /** job_id (jid+dad+aid) is composite key for activity */
     jid: string;
+    /** dimensional address for the activity (,0,0,1) */
     dad: string;
+    /** activity_id as in the YAML file */
     aid: string;
+    /** parent_job_id (pj+pd+pa) is composite key for parent activity */
     pj?: string;
+    /** parent_generational_id (system assigned at trigger inception); pg is the parent job's gid (just in case user created/deleted/created a job with same jid) */
     pg?: string;
+    /** parent_dimensional_address */
     pd?: string;
+    /** parent_activity_id */
     pa?: string;
+    /** sever the dependency chain if true (startChild/vs/execChild) */
     px?: boolean;
+    /** engine guid (one time subscriptions) */
     ngn?: string;
+    /** app_id */
     app: string;
+    /** app version */
     vrs: string;
+    /** subscription topic */
     tpc: string;
+    /** 201203120005 (slice of time) //time series */
     ts: string;
+    /** GMT created //job_created */
     jc: string;
+    /** GMT updated //job_updated */
     ju: string;
     js: JobStatus;
+    /** activity_type */
     atp: string;
+    /** activity_subtype */
     stp: string;
+    /** open telemetry span context */
     spn: string;
+    /** open telemetry trace context */
     trc: string;
+    /** stringified job error json: {message: string, code: number, error?} */
     err?: string;
+    /** process data expire policy */
     expire?: number;
 };
+/**
+ * job_status semaphore
+ */
 type JobStatus = number;
 type JobState = {
     metadata: JobMetadata;
@@ -44,28 +71,65 @@ type JobState = {
     };
 };
 type JobInterruptOptions = {
-    /** Optional reason when throwing the error  */
+    /**
+     * optional Reason; will be used as the error `message` when thrown
+     * @default 'Job Interrupted'
+     */
     reason?: string;
-    /** default is `true` when `undefined` (throw JobInterrupted/410 error) */
+    /**
+     * throw JobInterrupted error upon interrupting
+     * @default true
+     */
     throw?: boolean;
-    /** default behavior is `false` when `undefined` (do NOT interrupt child jobs) */
+    /**
+     * interrupt child/descendant jobs
+     * @default false
+     */
     descend?: boolean;
-    /** default is false; if true, errors related to inactivation (like overage...already inactive) are suppressed/ignored */
+    /**
+     * if true, errors related to inactivation (like overage...already inactive) are suppressed/ignored
+     * @default false
+     */
     suppress?: boolean;
-    /** how long to wait in seconds before fully expiring/removing the hash from Redis; the job is inactive, but can remain in the cache indefinitely. minimum 1 second.*/
+    /**
+     * how long to wait in seconds before fully expiring/removing the hash from Redis;
+     * the job is inactive, but can remain in the cache indefinitely;
+     * @default 1 second.
+     */
     expire?: number;
+    /**
+     * Optional Error Code; will be used as the error `code` when thrown
+     * @default 410
+     */
+    code?: number;
+    /**
+     * Optional stack trace
+     */
+    stack?: string;
 };
+/**
+ * format when publishing job meta/data on the wire when it completes
+ */
 type JobOutput = {
     metadata: JobMetadata;
     data: JobData;
 };
+/**
+ * jid+dad+aid is a composite guid; signal in and restore the full job context
+ */
 type PartialJobState = {
     metadata: JobMetadata | Pick<JobMetadata, 'jid' | 'dad' | 'aid'>;
     data: JobData;
 };
 type JobCompletionOptions = {
+    /** default false */
     emit?: boolean;
+    /** default undefined */
     interrupt?: boolean;
+    /**
+     * in seconds to wait before deleting/expiring job hash
+     * @default 1 second
+     */
     expire?: number;
 };
 export { JobCompletionOptions, JobInterruptOptions, JobData, JobsData, JobMetadata, JobOutput, JobState, JobStatus, PartialJobState, };

package/build/types/pipe.d.ts

@@ -1,4 +1,82 @@
-type PipeItem = string | boolean | number | null;
+/**
+ * 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[];
-type Pipe = (PipeItem[] | Pipe)[];
-export { Pipe, PipeItem, PipeItems };
+/**
+ * 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 };