@hotmeshio/hotmesh 0.5.1 → 0.5.2

package/README.md

@@ -16,11 +16,11 @@ Use HotMesh to:
 
 ## Table of Contents
 
-1. [Quick Start](#-quick-start)
-2. [Permanent Memory Architecture](#-permanent-memory-architecture)
-3. [Durable AI Agents](#-durable-ai-agents)
-4. [Building Pipelines with State](#-building-pipelines-with-state)
-5. [Documentation & Links](#-documentation--links)
+1. [Quick Start](#quick-start)
+2. [Permanent Memory Architecture](#permanent-memory-architecture)
+3. [Durable AI Agents](#durable-ai-agents)
+4. [Building Pipelines with State](#building-pipelines-with-state)
+5. [Documentation & Links](#documentation--links)
 
 ---
 
@@ -163,6 +163,8 @@ export async function researchAgent(query: string): Promise<any> {
 }
 ```
 
+> 💡 **Developer Note**: A complete implementation of this Research Agent example with tests, OpenAI integration, and multi-perspective analysis can be found in the [test suite](./tests/memflow/agent).
+
 #### Hooks: Perspectives
 
 ```ts
@@ -355,6 +357,8 @@ export async function triggerRefresh() {
 }
 ```
 
+> 💡 **Developer Note**: A complete implementation of this Pipeline example with OpenAI Vision integration, processing hooks, and document workflow automation can be found in the [test suite](./tests/memflow/pipeline).
+
 ---
 
 ## Documentation & Links

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.5.1",
+    "version": "0.5.2",
     "description": "Permanent-Memory Workflows & AI Agents",
     "main": "./build/index.js",
     "types": "./build/index.d.ts",
@@ -27,26 +27,27 @@
         "test:connect:postgres": "NODE_ENV=test jest ./tests/unit/services/connector/providers/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:connect:redis": "NODE_ENV=test jest ./tests/unit/services/connector/providers/redis.test.ts --detectOpenHandles --forceExit --verbose",
         "test:connect:nats": "NODE_ENV=test jest ./tests/unit/services/connector/providers/nats.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:cycle": "NODE_ENV=test jest ./tests/functional/cycle/*.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:memflow": "NODE_ENV=test jest ./tests/memflow/*/*.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:memflow": "NODE_ENV=test jest ./tests/memflow/*/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:basic": "HMSH_LOGLEVEL=info NODE_ENV=test jest ./tests/memflow/basic/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:collision": "NODE_ENV=test jest ./tests/memflow/collision/*.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:fatal": "NODE_ENV=test jest ./tests/memflow/fatal/*.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:goodbye": "NODE_ENV=test jest ./tests/memflow/goodbye/*.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:entity": "NODE_ENV=test HMSH_LOGLEVEL=debug jest ./tests/memflow/entity/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:agent": "NODE_ENV=test HMSH_LOGLEVEL=debug jest ./tests/memflow/agent/postgres.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:memflow:hello": "HMSH_TELEMETRY=debug HMSH_LOGLEVEL=debug HMSH_IS_CLUSTER=true NODE_ENV=test jest ./tests/memflow/helloworld/*.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:memflow:hook": "NODE_ENV=test jest ./tests/memflow/hook/*.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:memflow:interrupt": "NODE_ENV=test jest ./tests/memflow/interrupt/*.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:memflow:loopactivity": "NODE_ENV=test jest ./tests/memflow/loopactivity/*.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:memflow:nested": "NODE_ENV=test jest ./tests/memflow/nested/*.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:memflow:retry": "NODE_ENV=test jest ./tests/memflow/retry/*.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:memflow:sleep": "NODE_ENV=test jest ./tests/memflow/sleep/*.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:memflow:signal": "NODE_ENV=test jest ./tests/memflow/signal/*.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:memflow:unknown": "NODE_ENV=test jest ./tests/memflow/unknown/*.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:memflow:hello": "HMSH_TELEMETRY=debug HMSH_LOGLEVEL=debug HMSH_IS_CLUSTER=true NODE_ENV=test jest ./tests/memflow/helloworld/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:memflow:hook": "NODE_ENV=test jest ./tests/memflow/hook/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:memflow:interrupt": "NODE_ENV=test jest ./tests/memflow/interrupt/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:memflow:loopactivity": "NODE_ENV=test jest ./tests/memflow/loopactivity/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:memflow:nested": "NODE_ENV=test jest ./tests/memflow/nested/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:memflow:pipeline": "NODE_ENV=test jest ./tests/memflow/pipeline/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:memflow:retry": "NODE_ENV=test jest ./tests/memflow/retry/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:memflow:sleep": "NODE_ENV=test jest ./tests/memflow/sleep/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:memflow:signal": "NODE_ENV=test jest ./tests/memflow/signal/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:memflow:unknown": "NODE_ENV=test jest ./tests/memflow/unknown/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:cycle": "NODE_ENV=test jest ./tests/functional/cycle/*.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:functional": "NODE_ENV=test jest ./tests/functional/* --detectOpenHandles --forceExit --verbose",
         "test:emit": "NODE_ENV=test jest ./tests/functional/emit/*.test.ts --detectOpenHandles --forceExit --verbose",
         "test:pending": "NODE_ENV=test jest ./tests/functional/pending/index.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:functional": "NODE_ENV=test jest ./tests/functional/* --detectOpenHandles --forceExit --verbose",
         "test:hmsh": "NODE_ENV=test jest ./tests/functional/*.test.ts --detectOpenHandles --verbose --forceExit",
         "test:hook": "NODE_ENV=test jest ./tests/functional/hook/index.test.ts --detectOpenHandles --forceExit --verbose",
         "test:interrupt": "NODE_ENV=test jest ./tests/functional/interrupt/*.test.ts --detectOpenHandles --forceExit --verbose",
@@ -74,7 +75,6 @@
         "test:sub:postgres": "NODE_ENV=test jest ./tests/functional/sub/providers/postgres/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:sub:nats": "NODE_ENV=test jest ./tests/functional/sub/providers/nats/nats.test.ts --detectOpenHandles --forceExit --verbose",
         "test:trigger": "NODE_ENV=test jest ./tests/unit/services/activities/trigger.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:meshdata": "NODE_ENV=test jest ./tests/meshdata/postgres.test.ts --forceExit --verbose --detectOpenHandles",
         "test:meshos": "HMSH_LOGLEVEL=info NODE_ENV=test HMSH_IS_CLUSTER=true jest ./tests/meshos/*.test.ts --forceExit --verbose --detectOpenHandles",
         "test:meshcall": "NODE_ENV=test jest ./tests/meshcall/*.test.ts --forceExit --verbose --detectOpenHandles",
         "test:unit": "NODE_ENV=test jest ./tests/unit/*/*/index.test.ts --detectOpenHandles --forceExit --verbose"
@@ -109,6 +109,7 @@
         "@types/pg": "^8.10.0",
         "@typescript-eslint/eslint-plugin": "^5.62.0",
         "@typescript-eslint/parser": "^5.62.0",
+        "dotenv": "^16.3.1",
         "eslint": "^8.57.0",
         "eslint-config-prettier": "^9.1.0",
         "eslint-plugin-import": "^2.29.1",
@@ -117,6 +118,7 @@
         "javascript-obfuscator": "^4.1.1",
         "jest": "^29.5.0",
         "nats": "^2.28.0",
+        "openai": "^5.9.0",
         "pg": "^8.10.0",
         "redis": "^4.6.13",
         "rimraf": "^4.4.1",

package/build/services/hotmesh/index.d.ts

@@ -11,7 +11,7 @@ import { JobStatsInput, GetStatsOptions, IdsResponse, StatsResponse } from '../.
 import { StreamCode, StreamData, StreamDataResponse, StreamStatus } from '../../types/stream';
 /**
  * HotMesh is a distributed, reentrant process orchestration engine that transforms
- * Redis, Postgres, or NATS into a resilient service mesh capable of running
+ * Postgres into a resilient service mesh capable of running
  * fault-tolerant workflows across multiple services and systems.
  *
  * ## Core Concepts
@@ -25,14 +25,10 @@ import { StreamCode, StreamData, StreamDataResponse, StreamStatus } from '../../
  * provides built-in retry logic, idempotency, and failure recovery. Your business
  * logic doesn't need to handle timeouts or retries - the engine manages all of that.
  *
- * **Multi-Provider Support**: Supports Redis/ValKey, Postgres, and NATS as backend
- * providers, allowing you to leverage existing infrastructure investments.
- *
  * ## Key Features
  *
  * - **Fault Tolerance**: Automatic retry, timeout, and failure recovery
  * - **Distributed Execution**: No single point of failure
- * - **Multi-Provider**: Redis, Postgres, NATS backend support
  * - **YAML-Driven**: Model-driven development with declarative workflow definitions
  * - **OpenTelemetry**: Built-in observability and tracing
  * - **Durable State**: Workflow state persists across system restarts
@@ -59,15 +55,17 @@ import { StreamCode, StreamData, StreamDataResponse, StreamStatus } from '../../
  * @example
  * ```typescript
  * import { HotMesh } from '@hotmeshio/hotmesh';
- * import Redis from 'ioredis';
+ * import { Client as Postgres } from 'pg';
  *
- * // Initialize with Redis backend
+ * // Initialize with Postgres backend
  * const hotMesh = await HotMesh.init({
  *   appId: 'my-app',
  *   engine: {
  *     connection: {
- *       class: Redis,
- *       options: { host: 'localhost', port: 6379 }
+ *       class: Postgres,
+ *       options: {
+ *         connectionString: 'postgresql://user:pass@localhost:5432/db'
+ *       }
  *     }
  *   }
  * });
@@ -192,9 +190,9 @@ import { StreamCode, StreamData, StreamDataResponse, StreamStatus } from '../../
  * await HotMesh.stop();
  * ```
  *
- * @see {@link https://hotmesh.io/docs} - Complete documentation
+ * @see {@link https://docs.hotmesh.io/} - Complete documentation
  * @see {@link https://github.com/hotmeshio/samples-typescript} - Examples and tutorials
- * @see {@link https://zenodo.org/records/12168558} - Academic paper on the architecture
+ * @see {@link https://zenodo.org/records/12168558} - White paper on the architecture
  */
 declare class HotMesh {
     namespace: string;

package/build/services/hotmesh/index.js

@@ -12,7 +12,7 @@ const worker_1 = require("../worker");
 const enums_1 = require("../../modules/enums");
 /**
  * HotMesh is a distributed, reentrant process orchestration engine that transforms
- * Redis, Postgres, or NATS into a resilient service mesh capable of running
+ * Postgres into a resilient service mesh capable of running
  * fault-tolerant workflows across multiple services and systems.
  *
  * ## Core Concepts
@@ -26,14 +26,10 @@ const enums_1 = require("../../modules/enums");
  * provides built-in retry logic, idempotency, and failure recovery. Your business
  * logic doesn't need to handle timeouts or retries - the engine manages all of that.
  *
- * **Multi-Provider Support**: Supports Redis/ValKey, Postgres, and NATS as backend
- * providers, allowing you to leverage existing infrastructure investments.
- *
  * ## Key Features
  *
  * - **Fault Tolerance**: Automatic retry, timeout, and failure recovery
  * - **Distributed Execution**: No single point of failure
- * - **Multi-Provider**: Redis, Postgres, NATS backend support
  * - **YAML-Driven**: Model-driven development with declarative workflow definitions
  * - **OpenTelemetry**: Built-in observability and tracing
  * - **Durable State**: Workflow state persists across system restarts
@@ -60,15 +56,17 @@ const enums_1 = require("../../modules/enums");
  * @example
  * ```typescript
  * import { HotMesh } from '@hotmeshio/hotmesh';
- * import Redis from 'ioredis';
+ * import { Client as Postgres } from 'pg';
  *
- * // Initialize with Redis backend
+ * // Initialize with Postgres backend
  * const hotMesh = await HotMesh.init({
  *   appId: 'my-app',
  *   engine: {
  *     connection: {
- *       class: Redis,
- *       options: { host: 'localhost', port: 6379 }
+ *       class: Postgres,
+ *       options: {
+ *         connectionString: 'postgresql://user:pass@localhost:5432/db'
+ *       }
  *     }
  *   }
  * });
@@ -193,9 +191,9 @@ const enums_1 = require("../../modules/enums");
  * await HotMesh.stop();
  * ```
  *
- * @see {@link https://hotmesh.io/docs} - Complete documentation
+ * @see {@link https://docs.hotmesh.io/} - Complete documentation
  * @see {@link https://github.com/hotmeshio/samples-typescript} - Examples and tutorials
- * @see {@link https://zenodo.org/records/12168558} - Academic paper on the architecture
+ * @see {@link https://zenodo.org/records/12168558} - White paper on the architecture
  */
 class HotMesh {
     /**

package/build/services/memflow/entity.d.ts

@@ -62,7 +62,7 @@ export declare class Entity {
      * const entity = await workflow.entity();
      * await entity.set({ user: { id: 123, name: "John" } });
      */
-    set(value: any): Promise<any>;
+    set<T>(value: T): Promise<T>;
     /**
      * Deep merges the provided object with the existing entity
      *
@@ -79,7 +79,7 @@ export declare class Entity {
      * const user = await entity.get("user");
      * const email = await entity.get("user.email");
      */
-    get(path?: string): Promise<any>;
+    get<T>(path?: string): Promise<T>;
     /**
      * Deletes a value from the entity by path
      *
@@ -137,7 +137,171 @@ export declare class Entity {
      */
     setIfNotExists(path: string, value: any): Promise<any>;
     /**
-     * @private
+     * Finds entity records matching complex conditions using JSONB/SQL queries.
+     * This is a readonly operation that queries across all entities of a given type.
+     *
+     * @example
+     * ```typescript
+     * // Basic find with simple conditions
+     * const activeUsers = await Entity.find(
+     *   'user',
+     *   { status: 'active', country: 'US' },
+     *   hotMeshClient
+     * );
+     *
+     * // Complex query with comparison operators
+     * const seniorUsers = await Entity.find(
+     *   'user',
+     *   {
+     *     age: { $gte: 65 },
+     *     status: 'active',
+     *     'preferences.notifications': true
+     *   },
+     *   hotMeshClient,
+     *   { limit: 10, offset: 0 }
+     * );
+     *
+     * // Query with multiple conditions and nested objects
+     * const premiumUsers = await Entity.find(
+     *   'user',
+     *   {
+     *     'subscription.type': 'premium',
+     *     'subscription.status': 'active',
+     *     'billing.amount': { $gt: 100 },
+     *     'profile.verified': true
+     *   },
+     *   hotMeshClient,
+     *   { limit: 20 }
+     * );
+     *
+     * // Array conditions
+     * const taggedPosts = await Entity.find(
+     *   'post',
+     *   {
+     *     'tags': { $in: ['typescript', 'javascript'] },
+     *     'status': 'published',
+     *     'views': { $gte: 1000 }
+     *   },
+     *   hotMeshClient
+     * );
+     * ```
+     */
+    static find(entity: string, conditions: Record<string, any>, hotMeshClient: HotMesh, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<any[]>;
+    /**
+     * Finds a specific entity record by its ID using direct JSONB/SQL queries.
+     * This is the most efficient method for retrieving a single entity record.
+     *
+     * @example
+     * ```typescript
+     * // Basic findById usage
+     * const user = await Entity.findById('user', 'user123', hotMeshClient);
+     *
+     * // Example with type checking
+     * interface User {
+     *   id: string;
+     *   name: string;
+     *   email: string;
+     *   preferences: {
+     *     theme: 'light' | 'dark';
+     *     notifications: boolean;
+     *   };
+     * }
+     *
+     * const typedUser = await Entity.findById<User>('user', 'user456', hotMeshClient);
+     * console.log(typedUser.preferences.theme); // 'light' | 'dark'
+     *
+     * // Error handling example
+     * try {
+     *   const order = await Entity.findById('order', 'order789', hotMeshClient);
+     *   if (!order) {
+     *     console.log('Order not found');
+     *     return;
+     *   }
+     *   console.log('Order details:', order);
+     * } catch (error) {
+     *   console.error('Error fetching order:', error);
+     * }
+     * ```
+     */
+    static findById(entity: string, id: string, hotMeshClient: HotMesh): Promise<any>;
+    /**
+     * Finds entity records matching a specific field condition using JSONB/SQL queries.
+     * Supports various operators for flexible querying across all entities of a type.
+     *
+     * @example
+     * ```typescript
+     * // Basic equality search
+     * const activeUsers = await Entity.findByCondition(
+     *   'user',
+     *   'status',
+     *   'active',
+     *   '=',
+     *   hotMeshClient,
+     *   { limit: 20 }
+     * );
+     *
+     * // Numeric comparison
+     * const highValueOrders = await Entity.findByCondition(
+     *   'order',
+     *   'total_amount',
+     *   1000,
+     *   '>=',
+     *   hotMeshClient
+     * );
+     *
+     * // Pattern matching with LIKE
+     * const gmailUsers = await Entity.findByCondition(
+     *   'user',
+     *   'email',
+     *   '%@gmail.com',
+     *   'LIKE',
+     *   hotMeshClient
+     * );
+     *
+     * // IN operator for multiple values
+     * const specificProducts = await Entity.findByCondition(
+     *   'product',
+     *   'category',
+     *   ['electronics', 'accessories'],
+     *   'IN',
+     *   hotMeshClient
+     * );
+     *
+     * // Not equals operator
+     * const nonPremiumUsers = await Entity.findByCondition(
+     *   'user',
+     *   'subscription_type',
+     *   'premium',
+     *   '!=',
+     *   hotMeshClient
+     * );
+     *
+     * // Date comparison
+     * const recentOrders = await Entity.findByCondition(
+     *   'order',
+     *   'created_at',
+     *   new Date('2024-01-01'),
+     *   '>',
+     *   hotMeshClient,
+     *   { limit: 50 }
+     * );
+     * ```
+     */
+    static findByCondition(entity: string, field: string, value: any, operator: '=' | '!=' | '>' | '<' | '>=' | '<=' | 'LIKE' | 'IN', hotMeshClient: HotMesh, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<any[]>;
+    /**
+     * Creates an efficient GIN index for a specific entity field to optimize queries.
+     *
+     * @example
+     * ```typescript
+     * await Entity.createIndex('user', 'email', hotMeshClient);
+     * await Entity.createIndex('user', 'status', hotMeshClient);
+     * ```
      */
-    private deepMerge;
+    static createIndex(entity: string, field: string, hotMeshClient: HotMesh, indexType?: 'gin'): Promise<void>;
 }

package/build/services/memflow/entity.js

@@ -71,7 +71,7 @@ class Entity {
             '@context': JSON.stringify(value),
             [ssGuid]: '', // Pass replay ID to hash module for transactional replay storage
         });
-        return result || value;
+        return result;
     }
     /**
      * Deep merges the provided object with the existing entity
@@ -278,22 +278,184 @@ class Entity {
         });
         return newValue;
     }
+    // Static readonly find methods for cross-entity querying (not tied to specific workflow)
     /**
-     * @private
+     * Finds entity records matching complex conditions using JSONB/SQL queries.
+     * This is a readonly operation that queries across all entities of a given type.
+     *
+     * @example
+     * ```typescript
+     * // Basic find with simple conditions
+     * const activeUsers = await Entity.find(
+     *   'user',
+     *   { status: 'active', country: 'US' },
+     *   hotMeshClient
+     * );
+     *
+     * // Complex query with comparison operators
+     * const seniorUsers = await Entity.find(
+     *   'user',
+     *   {
+     *     age: { $gte: 65 },
+     *     status: 'active',
+     *     'preferences.notifications': true
+     *   },
+     *   hotMeshClient,
+     *   { limit: 10, offset: 0 }
+     * );
+     *
+     * // Query with multiple conditions and nested objects
+     * const premiumUsers = await Entity.find(
+     *   'user',
+     *   {
+     *     'subscription.type': 'premium',
+     *     'subscription.status': 'active',
+     *     'billing.amount': { $gt: 100 },
+     *     'profile.verified': true
+     *   },
+     *   hotMeshClient,
+     *   { limit: 20 }
+     * );
+     *
+     * // Array conditions
+     * const taggedPosts = await Entity.find(
+     *   'post',
+     *   {
+     *     'tags': { $in: ['typescript', 'javascript'] },
+     *     'status': 'published',
+     *     'views': { $gte: 1000 }
+     *   },
+     *   hotMeshClient
+     * );
+     * ```
      */
-    deepMerge(target, source) {
-        if (!source)
-            return target;
-        const output = { ...target };
-        Object.keys(source).forEach(key => {
-            if (source[key] instanceof Object && key in target) {
-                output[key] = this.deepMerge(target[key], source[key]);
-            }
-            else {
-                output[key] = source[key];
-            }
-        });
-        return output;
+    static async find(entity, conditions, hotMeshClient, options) {
+        // Use SearchService for JSONB/SQL querying
+        const searchClient = hotMeshClient.engine.search;
+        return await searchClient.findEntities(entity, conditions, options);
+    }
+    /**
+     * Finds a specific entity record by its ID using direct JSONB/SQL queries.
+     * This is the most efficient method for retrieving a single entity record.
+     *
+     * @example
+     * ```typescript
+     * // Basic findById usage
+     * const user = await Entity.findById('user', 'user123', hotMeshClient);
+     *
+     * // Example with type checking
+     * interface User {
+     *   id: string;
+     *   name: string;
+     *   email: string;
+     *   preferences: {
+     *     theme: 'light' | 'dark';
+     *     notifications: boolean;
+     *   };
+     * }
+     *
+     * const typedUser = await Entity.findById<User>('user', 'user456', hotMeshClient);
+     * console.log(typedUser.preferences.theme); // 'light' | 'dark'
+     *
+     * // Error handling example
+     * try {
+     *   const order = await Entity.findById('order', 'order789', hotMeshClient);
+     *   if (!order) {
+     *     console.log('Order not found');
+     *     return;
+     *   }
+     *   console.log('Order details:', order);
+     * } catch (error) {
+     *   console.error('Error fetching order:', error);
+     * }
+     * ```
+     */
+    static async findById(entity, id, hotMeshClient) {
+        // Use SearchService for JSONB/SQL querying
+        const searchClient = hotMeshClient.engine.search;
+        return await searchClient.findEntityById(entity, id);
+    }
+    /**
+     * Finds entity records matching a specific field condition using JSONB/SQL queries.
+     * Supports various operators for flexible querying across all entities of a type.
+     *
+     * @example
+     * ```typescript
+     * // Basic equality search
+     * const activeUsers = await Entity.findByCondition(
+     *   'user',
+     *   'status',
+     *   'active',
+     *   '=',
+     *   hotMeshClient,
+     *   { limit: 20 }
+     * );
+     *
+     * // Numeric comparison
+     * const highValueOrders = await Entity.findByCondition(
+     *   'order',
+     *   'total_amount',
+     *   1000,
+     *   '>=',
+     *   hotMeshClient
+     * );
+     *
+     * // Pattern matching with LIKE
+     * const gmailUsers = await Entity.findByCondition(
+     *   'user',
+     *   'email',
+     *   '%@gmail.com',
+     *   'LIKE',
+     *   hotMeshClient
+     * );
+     *
+     * // IN operator for multiple values
+     * const specificProducts = await Entity.findByCondition(
+     *   'product',
+     *   'category',
+     *   ['electronics', 'accessories'],
+     *   'IN',
+     *   hotMeshClient
+     * );
+     *
+     * // Not equals operator
+     * const nonPremiumUsers = await Entity.findByCondition(
+     *   'user',
+     *   'subscription_type',
+     *   'premium',
+     *   '!=',
+     *   hotMeshClient
+     * );
+     *
+     * // Date comparison
+     * const recentOrders = await Entity.findByCondition(
+     *   'order',
+     *   'created_at',
+     *   new Date('2024-01-01'),
+     *   '>',
+     *   hotMeshClient,
+     *   { limit: 50 }
+     * );
+     * ```
+     */
+    static async findByCondition(entity, field, value, operator = '=', hotMeshClient, options) {
+        // Use SearchService for JSONB/SQL querying
+        const searchClient = hotMeshClient.engine.search;
+        return await searchClient.findEntitiesByCondition(entity, field, value, operator, options);
+    }
+    /**
+     * Creates an efficient GIN index for a specific entity field to optimize queries.
+     *
+     * @example
+     * ```typescript
+     * await Entity.createIndex('user', 'email', hotMeshClient);
+     * await Entity.createIndex('user', 'status', hotMeshClient);
+     * ```
+     */
+    static async createIndex(entity, field, hotMeshClient, indexType = 'gin') {
+        // Use SearchService for index creation
+        const searchClient = hotMeshClient.engine.search;
+        return await searchClient.createEntityIndex(entity, field, indexType);
     }
 }
 exports.Entity = Entity;

package/build/services/memflow/workflow/index.d.ts

@@ -12,6 +12,7 @@ import { random } from './random';
 import { signal } from './signal';
 import { hook } from './hook';
 import { interrupt } from './interrupt';
+import { didInterrupt } from './interruption';
 import { all } from './all';
 import { sleepFor } from './sleepFor';
 import { waitFor } from './waitFor';
@@ -22,10 +23,6 @@ import { entity } from './entityMethods';
  * These methods ensure deterministic replay, persistence of state, and error handling across
  * re-entrant workflow executions.
  *
- * By refactoring the original single-file implementation into submodules,
- * we maintain clear separation of concerns and improved maintainability,
- * while preserving type information and full functionality.
- *
  * @example
  * ```typescript
  * import { MemFlow } from '@hotmeshio/hotmesh';
@@ -62,6 +59,7 @@ export declare class WorkflowService {
     static random: typeof random;
     static signal: typeof signal;
     static hook: typeof hook;
+    static didInterrupt: typeof didInterrupt;
     static interrupt: typeof interrupt;
     static all: typeof all;
     static sleepFor: typeof sleepFor;