@hotmeshio/hotmesh 0.0.56 → 0.0.58

package/build/types/quorum.d.ts

@@ -15,6 +15,7 @@ interface NetworkStat {
     tx_sec: number;
     ms: number;
 }
+/** reveals: memory, cpu, network */
 export interface SystemHealth {
     TotalMemoryGB: string;
     FreeMemoryGB: string;
@@ -23,10 +24,17 @@ 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; default is 0 */
     throttle: number;
+    /** namespace
+     * @default 'durable'
+     */
     namespace?: string;
 };
 export interface QuorumProfile {
@@ -115,5 +123,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;
 export {};

package/build/types/redis.d.ts

@@ -2,6 +2,9 @@
 import { StringStringType } from './serializer';
 import { ReclaimedMessageType } from './stream';
 type MultiResponseFlags = (string | number)[];
+/**
+ * Redis types
+ */
 interface ConnectionOptions {
     host?: string;
     port?: number;
@@ -135,6 +138,9 @@ interface RedisRedisClientType {
 interface RedisRedisClassType {
     createClient(options: RedisRedisClientOptions): Partial<RedisRedisClientType>;
 }
+/**
+ * IORedis types
+ */
 interface IORedisClientOptions {
     port?: number;
     host?: string;

package/build/types/stream.d.ts

@@ -1,19 +1,38 @@
+/** 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 {
@@ -27,28 +46,51 @@ 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 interface StreamDataResponse extends StreamData {
 }
 export declare enum StreamRole {
@@ -56,19 +98,35 @@ export declare enum StreamRole {
     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 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;
+    /** 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/hotmesh",
-  "version": "0.0.56",
+  "version": "0.0.58",
   "description": "Unbreakable Workflows",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",

package/types/durable.ts

@@ -118,7 +118,11 @@ type WorkflowSearchOptions = {
   prefix?: string[];
 
   /** 
-   * Schema mapping each field to a type with an optional sortable flag 
+   * 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, {
     /**
@@ -202,6 +206,11 @@ type WorkflowSearchOptions = {
      * @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 */