@hotmeshio/hotmesh 0.1.15 → 0.1.17

package/types/hotmesh.ts

@@ -1,5 +1,5 @@
 import { ILogger } from '../services/logger';
-import { HotMeshService } from '../services/hotmesh';
+import { HotMesh as HotMeshService } from '../services/hotmesh';
 
 import { HookRules } from './hook';
 import { RedisClass, RedisClient, RedisOptions } from './redis';
@@ -72,13 +72,14 @@ type HotMeshWorker = {
   redis?: RedisConfig;
   reclaimDelay?: number; //milliseconds
   reclaimCount?: number; //max number of times to reclaim a stream
-  callback: (payload: StreamData) => Promise<StreamDataResponse | void>;
+  callback: (payload: StreamData) => Promise<StreamDataResponse>;
 };
 
 type HotMeshConfig = {
   appId: string;
   namespace?: string;
   name?: string;
+  guid?: string;
   logger?: ILogger;
   logLevel?: LogLevel;
   engine?: HotMeshEngine;

package/types/index.ts

@@ -26,6 +26,7 @@ export {
   ActivityWorkflowDataType,
   ChildResponseType,
   ClientConfig,
+  ClientWorkflow,
   ContextType,
   ConnectionConfig,
   Connection,
@@ -47,18 +48,18 @@ export {
   WorkflowSearchSchema,
   WorkflowDataType,
   WorkflowOptions,
-} from './durable';
+} from './meshflow';
 export {
-  DurableChildErrorType,
-  DurableProxyErrorType,
-  DurableSleepErrorType,
-  DurableWaitForAllErrorType,
-  DurableWaitForErrorType,
+  MeshFlowChildErrorType,
+  MeshFlowProxyErrorType,
+  MeshFlowSleepErrorType,
+  MeshFlowWaitForAllErrorType,
+  MeshFlowWaitForErrorType,
 } from './error';
 export {
   ActivityAction,
   DependencyExport,
-  DurableJobExport,
+  MeshFlowJobExport,
   ExportCycles,
   ExportItem,
   ExportOptions,
@@ -116,6 +117,23 @@ export {
   KeyStoreParams,
   KeyType,
 } from './hotmesh';
+export {
+  MeshCallConnectParams,
+  MeshCallExecParams,
+  MeshCallCronParams,
+  MeshCallExecOptions,
+  MeshCallCronOptions,
+  MeshCallInterruptOptions,
+  MeshCallInterruptParams,
+  MeshCallFlushParams,
+} from './meshcall';
+export {
+  CallOptions,
+  MeshDataWorkflowOptions,
+  ConnectOptions,
+  ConnectionInput,
+  ExecInput,
+} from './meshdata';
 export {
   ActivateMessage,
   CronMessage,

package/types/job.ts

@@ -108,16 +108,34 @@ type ExtensionType = {
   marker?: StringStringType;
 
   /**
+   * Workflows that are 'pending' init with a status of `-1`.
+   *
    * If provided, the job will initialize in a pending state, reserving
    * only the job ID (HSETNX) and persisting search and marker (if provided).
    * If a `resume` signal is sent before the specified number of seconds,
    * the job will resume as normal, transitioning to the adjacent children
-   * of the trigger. If the job is not resumed within the number
+   * of the trigger.
+   * 
+   * If the job is not resumed within the number
    * of seconds specified, the job will be scrubbed. No dependencies
    * are added for a job in a pending state; however, dependencies
    * will be added after the job is resumed if relevant.
    */
   pending?: number;
+
+  /**
+   * Workflows that apply a status threshold will be initialized
+   * with a status value of 1m - statusThreshold.
+   * 
+   * The value provided should be the count of descendant activities
+   * (those that descend from the trigger) that should be allowed to
+   * remain open once 'done' event is emitted.
+   *
+   * If the job should not be removed from the cache, the `expire` field
+   * should be set to `0`.
+   *
+   */
+  statusThreshold?: number;
 };
 
 /**

package/types/meshcall.ts

@@ -0,0 +1,192 @@
+import { RedisConfig } from "./hotmesh";
+import { LogLevel } from "./logger";
+
+interface MeshCallExecOptions {
+  /**
+   * Cache id when caching, flushing and retrieving function results.
+   */
+  id: string;
+  /**
+   * Time to live for the cache key. For example, `1 day`, `1 hour`. Refer to the syntax for the `ms` NPM package.
+   */
+  ttl?: string; 
+  /**
+   * If true, the cache will first be flushed and the function will be executed.
+   */
+  flush?: boolean;
+}
+interface MeshCallConnectParams {
+  /**
+   * Log level for the worker
+   */
+  logLevel?: LogLevel;
+  /**
+   * Idempotent GUID for the worker and engine
+   */
+  guid?: string;
+  /**
+   * Namespace for grouping common functions
+   */
+  namespace?: string;
+  /**
+   * Unique topic for the worker function
+   */
+  topic: string;
+  /**
+   * Redis configuration for the worker
+   */
+  redis: RedisConfig;
+  /**
+   * The linked worker function that will be called
+   */
+  callback: (...args: any[]) => any;
+}
+
+interface MeshCallExecParams {
+  /**
+   * namespace for grouping common functions
+   */
+  namespace?: string;
+  /**
+   * topic assigned to the worker when it was connected
+   */
+  topic: string;
+  /**
+   * Arguments to pass to the worker function
+   */
+  args: any[];
+  /**
+   * Redis configuration
+   */
+  redis: RedisConfig;
+  /**
+   * Execution options like caching ttl
+   */
+  options?: MeshCallExecOptions;
+}
+
+interface MeshCallFlushOptions {
+  /**
+   * Cache id when caching/flushing/retrieving function results.
+   */
+  id: string;
+}
+
+interface MeshCallFlushParams {
+  /**
+   * namespace for grouping common functions
+   */
+  namespace?: string;
+  /**
+   * id for cached response to flush
+   */
+  id?: string;
+  /**
+   * topic assigned to the worker when it was connected
+   */
+  topic: string;
+  /**
+   * Redis configuration
+   */
+  redis: RedisConfig;
+  /**
+   * Options for the flush
+   */
+  options?: MeshCallFlushOptions;
+}
+interface MeshCallCronOptions {
+  /**
+   * Idempotent GUID for the function
+   * */
+  id: string;
+  /** 
+   * For example, `1 day`, `1 hour`. Fidelity is generally
+   * within 5 seconds. Refer to the syntax for the `ms` NPM package.
+   */
+  interval: string;
+  /**
+   * Maximum number of cycles to run before exiting the cron.
+   */
+  maxCycles?: number;
+  /**
+   * Time in seconds to sleep before invoking the first cycle.
+   * For example, `1 day`, `1 hour`. Fidelity is generally
+   * within 5 seconds. Refer to the syntax for the `ms` NPM package.
+   */
+  delay?: string;
+}
+
+interface MeshCallInterruptOptions {
+  /**
+   * Idempotent GUID for the cron function
+   */
+  id: string;
+}
+
+interface MeshCallCronParams {
+  /**
+   * Log level for the cron
+   */
+  logLevel?: LogLevel;
+  /**
+   * Idempotent GUID for the worker and engine used for the cron
+   */
+  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?: string;
+  /**
+   * Unique topic for the cron function to identify the worker
+   */
+  topic: string;
+  /**
+   * Redis configuration for the cron job
+   */
+  redis: RedisConfig;
+  /**
+   * Arguments to pass to the cron job; arguments will be passed to the callback
+   * each time it runs
+   */
+  args: any[];
+  /**
+   * linked worker function to run
+   */
+  callback: (...args: any[]) => any;
+  /**
+   * Options for the cron job
+   */
+  options: MeshCallCronOptions;
+}
+
+interface MeshCallInterruptParams {
+  /**
+   * namespace for grouping common functions
+   */
+  namespace?: string;
+  /**
+   * topic assigned to the cron worker when it was connected
+   */
+  topic: string;
+  /**
+   * Redis configuration
+   */
+  redis: RedisConfig;
+  /**
+   * Options for interrupting the cron
+   */
+  options: MeshCallInterruptOptions;
+}
+
+export {
+  MeshCallConnectParams,
+  MeshCallExecParams,
+  MeshCallCronParams,
+  MeshCallExecOptions,
+  MeshCallCronOptions,
+  MeshCallInterruptOptions,
+  MeshCallInterruptParams,
+  MeshCallFlushOptions,
+  MeshCallFlushParams,
+};

package/types/meshdata.ts

@@ -0,0 +1,273 @@
+import { HookOptions, WorkflowConfig, WorkflowSearchOptions } from "./meshflow";
+import { StringStringType } from "./serializer";
+
+export type CallOptions = {
+  /**
+   * if provided along with a `ttl`, the function will be cached
+   */
+  id?: string;
+  /**
+   * in format '1 minute', '5 minutes', '1 hour', 'infinity', etc
+   */
+  ttl?: string;
+  /**
+   * full GUID (including prefix)
+   */
+  $guid?: string;
+  /**
+   * exec, hook, proxy
+   */
+  $type?: string;
+  /**
+   * if set to false explicitly it will not await the result
+   */
+  await?: boolean;
+  /**
+   * taskQueue for the workflowId (defaults to entity)
+   */
+  taskQueue?: string;
+  /**
+   * defaults to `entity` input parameter; allows override of the workflowId prefix
+   */
+  prefix?: string;
+  search?: WorkflowSearchOptions;
+  /**
+   * list of  state field names to return (this is NOT the final response)
+   */
+  fields?: string[];
+  /**
+   * namespace for the the execution client; how it appears in Redis (defaults to 'durable')
+   */
+  namespace?: string; //optional namespace for the workflowId (defaults to 'durable')
+
+  /**
+   * Custom marker data field used for adding a searchable marker to the job.
+   * markers always begin with a dash (-). Any field that does not
+   * begin with a dash will be removed and will not be inserted with
+   * the initial data set.
+   */
+  marker?: StringStringType;
+
+  /**
+   * If provided, the job will initialize in an pending state, reserving
+   * only the job ID (HSETNX) and persisting search and marker (if provided).
+   * If a `resume` signal is sent before the specified number of seconds,
+   * the job will resume as normal. If the job is not resumed within the
+   * number of seconds provided, the job will be scrubbed. No dependencies
+   * are set for a job in a pending state; however, dependencies will be
+   * added after the job is resumed if necessary.
+   */
+  pending?: number;
+
+  //flush?: boolean;
+};
+
+export type ConnectOptions = {
+  /**
+   * if set to infinity, callers may not override (the function will be durable)
+   */
+  ttl?: string;
+  /**
+   * the task queue for the connected function for greater specificity
+   */
+  taskQueue?: string;
+  /**
+   * prefix for the workflowId (defaults to entity value if not provided)
+   */
+  prefix?: string; 
+  /**
+   * optional namespace for the the worker; how it appears in Redis (defaults to 'durable')
+   */
+  namespace?: string; //optional namespace for the workflowId (defaults to 'durable')
+  /**
+   * extended worker options
+   */
+  options?: WorkerOptions;
+  /**
+   * optional search configuration
+   */
+  search?: WorkflowSearchOptions;
+};
+
+/**
+ * Connect a function to the operational data layer.
+ * @template T - the return type of the connected function
+ */
+export type ConnectionInput<T> = {
+  /**
+   * The connected function's entity identifier
+   * 
+   * @example
+   * user
+   */
+  entity: string;
+  /**
+   * The target function reference
+   * 
+   * @example
+   * function() { return "hello world" }
+   */
+  target: (...args: any[]) => T;
+  /**
+   * Extended connection options (e.g., ttl, taskQueue)
+   * @example
+   * { ttl: 'infinity' }
+   */
+  options?: ConnectOptions;
+};
+
+/**
+ * Executes a remote function by its global entity identifier with specified arguments.
+ * If options.ttl is infinity, the function will be cached indefinitely and can only be
+ * removed by calling `flush`. During this time, the function will remain active and can
+ * its state can be augmented by calling `set`, `incr`, `del`, etc OR by calling a
+ * transactional 'hook' function.
+ * 
+ * @template T The expected return type of the remote function.
+ */
+export type ExecInput = {
+  /**
+   * the connected function's entity identifier
+   * @example
+   * user
+   */
+  entity: string;
+  /**
+   * the function's input arguments
+   * @example
+   * ['Jane', 'Doe']
+   */
+  args: any[];
+  /**
+   * Extended options for the hook function, like specifying a taskQueue or ttl
+   * @example
+   * { ttl: '5 minutes' }
+   */
+  options?: Partial<MeshDataWorkflowOptions>;
+};
+
+/**
+ * Hook function inputs. Hooks augment running jobs.
+ */
+export type HookInput = {
+  /**
+   * The target function's entity identifier
+   * @example 'user'
+   */
+  entity: string;
+  /**
+   * The target execution id (workflowId/jobId)
+   * @example 'jsmith123'
+   */
+  id: string;
+  /**
+   * The hook function's entity identifier
+   * @example 'user.notify'
+   */
+  hookEntity: string;
+  /**
+   * The hook function's input arguments
+   * @example 'notify'
+   */
+  hookArgs: any[];
+  /**
+   * Extended options for the hook function, like specifying a taskQueue
+   * @example { taskQueue: 'priority' }
+   */
+  options?: Partial<HookOptions>;
+};
+
+
+export type MeshDataWorkflowOptions = {
+  /**
+   * The app deployment namespace; how it appears in redis (e.g., 'durable')
+   */
+  namespace?: string;
+
+  /**
+   * Target connected functions more specifically by taskQueue
+   */
+  taskQueue?: string;
+
+  /**
+   * The connected function's entity identifier
+   */
+  prefix?: string;
+
+  /**
+   * The function execution id (shorthand for workflowId)
+   */
+  id?: string;
+
+  /**
+   * The function execution id
+   */
+  workflowId?: string;
+
+  /**
+   * The function name (`entity` is a shorthand for this)
+   */
+  workflowName?: string;
+
+  /**
+   * The open telemetry trace context for the workflow, used for logging and tracing. If a sink is enabled, this will be sent to the sink.
+   */
+  workflowTrace?: string;
+
+  /**
+   * 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;
+
+  /**
+   * Search fields to seed function state when it first initializes
+   */
+  search?: WorkflowSearchOptions;
+
+  /**
+   * Extended execution options
+   */
+  config?: WorkflowConfig;
+
+  /**
+   * Set to 'infinity' to make the function durable; otherwise, '1 minute', '1 hour', etc
+   */
+  ttl?: string;
+
+  /**
+   * If set to false explicitly it will not await the result
+   * @default true
+   */
+  await?: boolean;
+
+  /**
+   * Custom marker data field used for adding a searchable marker to the job.
+   * markers always begin with a dash (-). Any field that does not
+   * begin with a dash will be removed and will not be inserted with
+   * the initial data set.
+   */
+  marker?: StringStringType;
+
+  /**
+   * If provided, the job will initialize in a pending state, reserving
+   * only the job ID (HSETNX) and persisting search and marker (if provided).
+   * If a `resume` signal is sent before the specified number of seconds,
+   * the job will resume as normal. If the job is not resumed within the
+   * number of seconds provided, the job will be scrubbed. No dependencies
+   * are set for a job in a pending state; however, dependencies will be
+   * added after the job is resumed (if necessary).
+   */
+  pending?: number;
+
+  /**
+   * 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.
+   * @default 1
+   */
+  expire?: number;
+
+  /**
+   * set to false to optimize workflows that do not require a `signal in`
+   * @default true
+   */
+  signalIn?: boolean;
+};

package/types/{durable.ts → meshflow.ts}

@@ -1,3 +1,4 @@
+import { WorkflowHandleService } from '../services/meshflow/handle';
 import { LogLevel } from './logger';
 import { RedisClass, RedisOptions } from './redis';
 import { StringAnyType, StringStringType } from './serializer';
@@ -9,19 +10,19 @@ import { StreamData, StreamError } from './stream';
 type WorkflowConfig = {
   /**
    * Backoff coefficient for retry mechanism.
-   * @default 10 (HMSH_DURABLE_EXP_BACKOFF)
+   * @default 10 (HMSH_MESHFLOW_EXP_BACKOFF)
    */
   backoffCoefficient?: number;
 
   /**
    * Maximum number of attempts for retries.
-   * @default 5 (HMSH_DURABLE_MAX_ATTEMPTS)
+   * @default 5 (HMSH_MESHFLOW_MAX_ATTEMPTS)
    */
   maximumAttempts?: number;
 
   /**
    * Maximum interval between retries.
-   * @default 120s (HMSH_DURABLE_MAX_INTERVAL)
+   * @default 120s (HMSH_MESHFLOW_MAX_INTERVAL)
    */
   maximumInterval?: string;
 
@@ -335,6 +336,13 @@ type WorkflowOptions = {
    * will be added after the job is resumed if relevant.
    */
   pending?: number;
+
+  /**
+   * Provide to set the engine name. This MUST be unique, so do not
+   * provide unless it is guaranteed to be a unique engine/worker guid
+   * when identifying the point of presence within the mesh.
+   */
+  guid?: string;
 };
 
 /**
@@ -446,6 +454,13 @@ type WorkerConfig = {
 
   /** Search options for workflow execution details */
   search?: WorkflowSearchOptions;
+
+  /**
+   * Provide to set the engine name. This MUST be unique, so do not
+   * provide unless it is guaranteed to be a unique engine/worker guid
+   * when identifying the point of presence within the mesh.
+   */
+  guid?: string;
 };
 
 type FindWhereQuery = {
@@ -495,13 +510,13 @@ type WorkerOptions = {
   /** Log level: debug, info, warn, error */
   logLevel?: LogLevel;
 
-  /** Maximum number of attempts, default 5 (HMSH_DURABLE_MAX_ATTEMPTS) */
+  /** Maximum number of attempts, default 5 (HMSH_MESHFLOW_MAX_ATTEMPTS) */
   maximumAttempts?: number;
 
-  /** Backoff coefficient for retry logic, default 10 (HMSH_DURABLE_EXP_BACKOFF) */
+  /** Backoff coefficient for retry logic, default 10 (HMSH_MESHFLOW_EXP_BACKOFF) */
   backoffCoefficient?: number;
 
-  /** Maximum interval between retries, default 120s (HMSH_DURABLE_MAX_INTERVAL) */
+  /** Maximum interval between retries, default 120s (HMSH_MESHFLOW_MAX_INTERVAL) */
   maximumInterval?: string;
 };
 
@@ -532,11 +547,11 @@ type ActivityConfig = {
 
   /** Retry policy configuration for activities */
   retryPolicy?: {
-    /** Maximum number of retry attempts, default is 5 (HMSH_DURABLE_MAX_ATTEMPTS) */
+    /** Maximum number of retry attempts, default is 5 (HMSH_MESHFLOW_MAX_ATTEMPTS) */
     maximumAttempts?: number;
-    /** Factor by which the retry timeout increases, default is 10 (HMSH_DURABLE_MAX_INTERVAL) */
+    /** Factor by which the retry timeout increases, default is 10 (HMSH_MESHFLOW_MAX_INTERVAL) */
     backoffCoefficient?: number;
-    /** Maximum interval between retries, default is '120s' (HMSH_DURABLE_EXP_BACKOFF) */
+    /** Maximum interval between retries, default is '120s' (HMSH_MESHFLOW_EXP_BACKOFF) */
     maximumInterval?: string;
     /** Whether to throw an error on failure, default is true */
     throwOnError?: boolean;
@@ -565,11 +580,20 @@ type ChildResponseType<T> = {
   ju: string;
 };
 
+interface ClientWorkflow {
+  start(options: WorkflowOptions): Promise<WorkflowHandleService>;
+  signal(signalId: string, data: StringAnyType, namespace?: string): Promise<string>;
+  hook(options: HookOptions): Promise<string>;
+  getHandle(taskQueue: string, workflowName: string, workflowId: string, namespace?: string): Promise<WorkflowHandleService>;
+  search(taskQueue: string, workflowName: string, namespace: string | null, index: string, ...query: string[]): Promise<string[]>;
+}
+
 export {
   ActivityConfig,
   ActivityWorkflowDataType,
   ChildResponseType,
   ClientConfig,
+  ClientWorkflow,
   ContextType,
   ConnectionConfig,
   Connection,