@hotmeshio/hotmesh 0.0.51 → 0.0.53

package/types/job.ts

@@ -7,34 +7,85 @@ type ActivityData = {
 };
 
 type JobMetadata = {
-  key?: string; //job_key
-  guid?: string; //system assigned guid that corresponds to the transition message guid that spawned reentry
-  gid: string;  //system assigned guid; ensured created/deleted/created jobs are unique
-  jid: string;  //job_id (jid+dad+aid) is composite key for activity
-  dad: string;  //dimensional address for the activity (,0,0,1)
-  aid: string;  //activity_id as in the YAML file
-  pj?: string;  //parent_job_id (pj+pd+pa) is composite key for parent activity
-  pg?: 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)
-  pd?: string;  //parent_dimensional_address
-  pa?: string;  //parent_activity_id
-  px?: boolean; //sever the dependency chain if true (startChild/vs/executeChild)
-  ngn?: string; //engine guid (one time subscriptions)
-  app: string;  //app_id
-  vrs: string;  //app version
-  tpc: string;  //subscription topic
-  ts: string    //201203120005 (slice of time) //time series
-  jc: string;   //GMT created //job_created
-  ju: string;   //GMT updated //job_updated
+  /** 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;
-  atp: string;  //activity_type
-  stp: string;  //activity_subtype
-  spn: string;  //open telemetry span context
-  trc: string;  //open telemetry trace context
-  err?: string; //stringified job error json: {message: string, code: number, error?}
-  expire?: number; //process data expire policy
+  
+  /** 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;
 };
 
-type JobStatus = number;       //job_status semaphore 
+/**
+ * job_status semaphore
+ */
+type JobStatus = number;
 
 type JobState = {
   metadata: JobMetadata;
@@ -49,35 +100,78 @@ 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
+/**
+ * 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
+/**
+ * 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 = {
-  emit?: boolean;      //default false
-  interrupt?: boolean;  //default undefined
-  expire?: number;      // in seconds to wait before deleting/expiring job hash
-}
+  /** default false */
+  emit?: boolean;
+  
+  /** default undefined */
+  interrupt?: boolean;
+  
+  /**
+   * in seconds to wait before deleting/expiring job hash
+   * @default 1 second
+   */
+  expire?: number;
+};
 
 export {
   JobCompletionOptions,

package/types/pipe.ts

@@ -1,7 +1,88 @@
-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)[];
+/**
+ * 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> };
 
-export { Pipe, PipeItem, PipeItems };
+/**
+ * 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/types/stream.ts

@@ -1,21 +1,41 @@
+/** Represents a policy for retrying stream operations based on error codes */
 export interface StreamRetryPolicy {
-  [key: string]: [number, 'x']; //key is err code, val is the retry profile [(max retry count),(type (x:exponential (default)) (only 10, 100, 1000, 10000 allowed))
+  /** 
+   * 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'?];
 }
 
-export type StreamCode = number; //3-digit status code
+/** 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;
-  job_id?: string; //used when communicating errors externally
-  stack?: string;  //unhandled errors will have a stack
-  name?: string;   //unhandled errors will have a name
-  error?: Record<string, unknown>; //custom user-defined error details go here
+  /** 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 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',
 }
 
@@ -31,28 +51,52 @@ export enum StreamDataType {
   INTERRUPT = 'interrupt',
 }
 
+/** Defines the structure of stream data used when passing stream messages (transitions) */
 export interface StreamData {
+  /** Metadata associated with the stream data */
   metadata: {
-    guid: string;   //every message is minted with a guid to distinguish retries from new messages
+    /** Globally unique identifier for the StreamData message to distinguish `retries` from new 'reentry/cycles' */
+    guid: string;
+    /** Workflow/job topic */
     topic?: string;
-    jid?: string;   //is optional if type is WEBHOOK (system assigned or user assigned)
-    gid?: string;   //is optional if type is WEBHOOK (system assigned job guid)
-    dad?: string;   //dimensional address
+    /** 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;
-    trc?: string;   //trace id
-    spn?: string;   //span id
-    try?: number;   //current try count
-    await?: boolean;  //(waitfor) if explicitly false, do not await; sever the connection
+    /** 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?: StreamStatus; //assume success
-  code?: number;         //assume 200
+  /** 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 enum StreamRole {
@@ -60,21 +104,36 @@ export enum StreamRole {
   ENGINE = 'engine',
   SYSTEM = 'system', //reserved for system use (i.e, if worker or engine fails)
 }
-
+/** 
+ * 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 = [
-  messageId: string, //stream id (e.g.,`<timestamp>-<count>`)
+  /** The stream ID, typically formatted as `<timestamp>-<count>` */
+  messageId: string,
+  /** Details of the message, consisting of a key and its value */
   details: [
-    key: string,     //`key' is always 'message'
-    value: string    //`value` is stringified StreamData (StreamDataType)
+    /** Key is always 'message' */
+    key: string,
+    /** Value is a stringified representation of StreamData */
+    value: string
   ]
-][];                 //wrapped in an outer array
+][];
 
+/** 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;
-  reclaimDelay?: number; //default 60_000
-  reclaimCount?: number; //default 3 (any value greater throws an error)
+  /** 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/services/durable/factory.d.ts

@@ -1,17 +0,0 @@
-/**
- * NOTE: Using `maxSystemRetries = 3` and `backoffCoefficient = 10`, errant
- *       workflows will be retried on the following schedule (8 times in 27 hours):
- *       => 10ms, 100ms, 1000ms, 10s, 100s, 1_000s, 10_000s, 100_000s
- * TODO: Max Interval, Min Interval, Initial Interval
- *
- * ERROR CODES:
- *      594: waitforsignal
- *      592: sleepFor
- *      596, 597, 598: fatal
- *      599: retry
- */
-declare const getWorkflowYAML: (app: string, version: string) => string;
-declare const APP_VERSION = "1";
-declare const APP_ID = "durable";
-declare const DEFAULT_COEFFICIENT = 10;
-export { getWorkflowYAML, APP_VERSION, APP_ID, DEFAULT_COEFFICIENT, };