@hotmeshio/hotmesh 0.0.57 → 0.0.58

package/build/types/durable.d.ts

@@ -2,85 +2,306 @@ import { LogLevel } from './logger';
 import { RedisClass, RedisOptions } from './redis';
 import { StringAnyType, 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;
+    /**
+     * 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.
+     */
     counter: number;
+    /**
+     * number as string for the replay cursor
+     */
     cursor: string;
+    /**
+     * the replay hash of name/value pairs representing prior executions
+     */
     replay: StringStringType;
+    /**
+     * the HotMesh App namespace. `durable` is the default.
+     */
     namespace: string;
+    /**
+     * holds list of interruption payloads; if list is longer than 1 when the error is thrown, a `collator` subflow will be used
+     */
     interruptionRegistry: any[];
+    /**
+     * entry point ancestor flow; might be the parent; will never be self
+     */
     originJobId: string;
+    /**
+     * the workflow/job ID
+     */
     workflowId: string;
+    /**
+     * the dimensional isolation for the reentrant hook, expressed in the format `0,0`, `0,1`, etc
+     */
     workflowDimension: string;
+    /**
+     * a concatenation of the task queue and workflow name (e.g., `${taskQueueName}-${workflowName}`)
+     */
     workflowTopic: 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;
+    /**
+     * 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. Each field is a key-value pair where the key is the field name
+     * and the value is a record of field options. If the fieldName is provided,
+     * it will be used as the indexed field name. If not provided
+     * key will be used as the indexed field name with an underscore prefix.
+     *
+     */
     schema?: Record<string, {
+        /**
+         * The FT.SEARCH field type. One of: TEXT, NUMERIC, TAG. TEXT is
+         * most expensive, but also most expressive.
+         */
         type: 'TEXT' | 'NUMERIC' | 'TAG';
+        /**
+         * FT.SEARCH SORTABLE field. If true, results may be sorted according to this field
+         * @default false
+         */
         sortable?: boolean;
+        /**
+         * FT.SEARCH NOSTEM field. applies to TEXT fields types.
+         * If true, the text field index will not stem words
+         * @default false
+         */
         nostem?: boolean;
+        /**
+         * FT.SEARCH NOINDEX field. If true and if the field is sortable, the field will aid
+         * in sorting results but not be directly indexed as a standalone
+         * @default false
+         */
         noindex?: boolean;
+        /**
+         * if true, the field is indexed and searchable within the FT.SEARCH index
+         * This is different from `noindex` which is FT.SEARCH specific and relates
+         * to sorting and indexing. This is a general flag for the field that will
+         * enable or disable indexing and searching entirely. Use for fields with
+         * absolutely no meaning to query or sorting but which are important
+         * nonetheless as part of the data record that is saved and returned.
+         * @default true
+         */
         indexed?: boolean;
+        /**
+         * An array of possible values for the field
+         */
         examples?: string[];
+        /**
+         * The 'nilable' setting may NOT be set to `true` for
+         * NUMBER types as it causes an indexing error;
+         * consider a custom (e.g., negative number) value to represent
+         * `null` if desired for a NUMERIC field.
+         * Set to true only if the field is a TEXT or TAG type and
+         * you wish to save the string `null` as a value to search
+         * on (the tag, {null}, or the string, (null)
+         * @default false
+         */
         nilable?: boolean;
+        /**
+         * possible scalar/primitive types for the field. Use when
+         * serializing and restoring data to ensure the field is
+         * properly typed. If not provided, the field will be
+         * treated as a string.
+         */
         primitive?: 'string' | 'number' | 'boolean' | 'array' | 'object';
+        /**
+         * if true, the field is required to be present in the data record
+         * @default false
+         */
         required?: boolean;
+        /**
+         * an enumerated list of allowed values; if field is nilable, it is implied
+         * and therefore not necessary to include `null` in the list
+         * @default []
+         */
         enum?: string[];
+        /**
+         * a regular expression pattern for the field
+         * @default '.*'
+         * @example '^[a-zA-Z0-9_]*$'
+         */
         pattern?: string;
+        /**
+         * literal value to use for the indexed field name (without including the standard underscore (_) prefix isolate)
+         */
         fieldName?: string;
     }>;
+    /** Additional data as a key-value record */
     data?: StringStringType;
 };
 type SearchResults = {
+    /**
+     * the total number of results
+     */
     count: number;
+    /**
+     * the raw FT.SEARCH query string
+     */
     query: string;
+    /**
+     * the raw FT.SEARCH results as an array of objects
+     */
     data: StringStringType[];
 };
 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;
+    /**
+     * marker data (begins with a -)
+     */
     marker?: StringStringType;
+    /**
+     * 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: StringAnyType;
+    /**
+     * Execution ID, also known as the job ID
+     */
     workflowId: string;
+    /**
+     * Optional name of the user's workflow function
+     */
     workflowName?: string;
 };
 type ActivityWorkflowDataType = {
@@ -109,11 +330,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 = {
@@ -140,16 +370,25 @@ type FindWhereOptions = {
     };
 };
 type FindJobsOptions = {
+    /** The workflow name; include an asterisk for wilcard search; refer to Redis SCAN for the allowed format */
     match?: string;
+    /** application namespace; defaults to 'durable' */
     namespace?: string;
+    /** The suggested response limit. Reduce batch size to reduce the likelihood of large overages. */
     limit?: number;
+    /** How many records to scan at a time */
     batch?: number;
+    /** The start cursor; defaults to 0 */
     cursor?: string;
 };
 type WorkerOptions = {
+    /** Log level: debug, info, warn, error */
     logLevel?: LogLevel;
+    /** 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 = {
@@ -160,16 +399,29 @@ 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?: {
+        /** 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;
     };
 };
+/**
+ * The proxy response object returned from the activity proxy flow
+ */
 type ProxyResponseType<T> = {
     data?: T;
     $error?: StreamError;
@@ -177,6 +429,9 @@ type ProxyResponseType<T> = {
     jc: string;
     ju: string;
 };
+/**
+ * The child flow response object returned from the  main flow during recursion
+ */
 type ChildResponseType<T> = {
     data?: T;
     $error?: StreamError;

package/build/types/exporter.d.ts

@@ -1,9 +1,22 @@
 import { StringAnyType } from "./serializer";
 export type ExportItem = [(string | null), string, any];
+/**
+ * job export data can be large, particularly transitions the timeline
+ */
 export type ExportFields = 'data' | 'state' | 'status' | 'timeline' | 'transitions';
 export interface ExportOptions {
+    /**
+     * limit the export byte size by specifying an allowlist
+     */
     allow?: Array<ExportFields>;
+    /**
+     * limit the export byte size by specifying a block list
+     */
     block?: Array<ExportFields>;
+    /**
+     * If false, do not return timeline values (like child job response, proxy activity response, etc)
+     * @default true
+     */
     values?: boolean;
 }
 export type JobAction = {

package/build/types/hotmesh.d.ts

@@ -4,6 +4,9 @@ import { HookRules } from './hook';
 import { RedisClass, RedisClient, RedisOptions } from './redis';
 import { StreamData, StreamDataResponse } from './stream';
 import { LogLevel } from './logger';
+/**
+ * the full set of entity types that are stored in the key/value store
+ */
 declare enum KeyType {
     APP = "APP",
     ENGINE_ID = "ENGINE",
@@ -25,6 +28,9 @@ declare enum KeyType {
     TIME_RANGE = "TIME_RANGE",
     WORK_ITEMS = "WORK_ITEMS"
 }
+/**
+ * minting keys, requires one or more of the following parameters
+ */
 type KeyStoreParams = {
     appId?: string;
     engineId?: string;
@@ -108,4 +114,7 @@ type HotMeshApp = VersionedFields & {
 type HotMeshApps = {
     [appId: string]: HotMeshApp;
 };
-export { HotMesh, HotMeshEngine, RedisConfig, HotMeshWorker, HotMeshSettings, HotMeshApp, HotMeshApps, HotMeshConfig, HotMeshManifest, HotMeshGraph, KeyType, KeyStoreParams, };
+export { HotMesh, HotMeshEngine, RedisConfig, HotMeshWorker, HotMeshSettings, HotMeshApp, //a single app in the db
+HotMeshApps, //object array of all apps in the db
+HotMeshConfig, //customer config
+HotMeshManifest, HotMeshGraph, KeyType, KeyStoreParams, };

package/build/types/hotmesh.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KeyType = void 0;
+/**
+ * the full set of entity types that are stored in the key/value store
+ */
 var KeyType;
 (function (KeyType) {
     KeyType["APP"] = "APP";

package/build/types/index.js

@@ -7,7 +7,7 @@ var hook_1 = require("./hook");
 Object.defineProperty(exports, "HookGate", { enumerable: true, get: function () { return hook_1.HookGate; } });
 var hotmesh_1 = require("./hotmesh");
 Object.defineProperty(exports, "KeyType", { enumerable: true, get: function () { return hotmesh_1.KeyType; } });
-var redis_1 = require("./redis");
+var redis_1 = require("./redis"); //common redis types
 Object.defineProperty(exports, "isRedisClient", { enumerable: true, get: function () { return redis_1.isRedisClient; } });
 Object.defineProperty(exports, "isIORedisClient", { enumerable: true, get: function () { return redis_1.isIORedisClient; } });
 var stream_1 = require("./stream");

package/build/types/job.d.ts

@@ -6,36 +6,81 @@ 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;
 };
+/**
+ * User-defined (extended) types for job data. Users may interleave
+ * data into the job hash safely by using the `ExtensionType` interface.
+ * The data will be prefixed as necessary using an underscore or
+ * dash to ensure it is not confused with system process data.
+ */
 type ExtensionType = {
+    /**
+     * Custom search data field (name/value pairs) to seed the Hash.
+     * Every field will be prefixed with an underscore before being
+     * stored with the initial Hash data set along side system
+     * process data.
+     */
     search?: StringStringType;
+    /**
+     * 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;
 };
+/**
+ * job_status semaphore
+ */
 type JobStatus = number;
 type JobState = {
     metadata: JobMetadata;
@@ -49,25 +94,65 @@ type JobState = {
     };
 };
 type JobInterruptOptions = {
+    /**
+     * optional Reason; will be used as the error `message` when thrown
+     * @default 'Job Interrupted'
+     */
     reason?: string;
+    /**
+     * throw JobInterrupted error upon interrupting
+     * @default true
+     */
     throw?: boolean;
+    /**
+     * interrupt child/descendant jobs
+     * @default false
+     */
     descend?: boolean;
+    /**
+     * 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;
+     * @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, JobData, JobsData, JobInterruptOptions, JobMetadata, JobOutput, JobState, JobStatus, PartialJobState, ExtensionType, };

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 };