@hotmeshio/hotmesh 0.5.1 → 0.5.3

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;

package/build/services/memflow/workflow/index.js

@@ -15,6 +15,7 @@ const random_1 = require("./random");
 const signal_1 = require("./signal");
 const hook_1 = require("./hook");
 const interrupt_1 = require("./interrupt");
+const interruption_1 = require("./interruption");
 const all_1 = require("./all");
 const sleepFor_1 = require("./sleepFor");
 const waitFor_1 = require("./waitFor");
@@ -25,10 +26,6 @@ const entityMethods_1 = require("./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';
@@ -80,6 +77,7 @@ WorkflowService.entity = entityMethods_1.entity;
 WorkflowService.random = random_1.random;
 WorkflowService.signal = signal_1.signal;
 WorkflowService.hook = hook_1.hook;
+WorkflowService.didInterrupt = interruption_1.didInterrupt;
 WorkflowService.interrupt = interrupt_1.interrupt;
 WorkflowService.all = all_1.all;
 WorkflowService.sleepFor = sleepFor_1.sleepFor;

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

@@ -1,18 +1,20 @@
 /**
  * Checks if an error is a HotMesh reserved error type that indicates
- * a workflow interruption rather than a true error condition.
+ * a HotMesh interruption rather than a true error condition.
  *
- * When this returns true, you can safely return from your workflow function.
+ * When this returns true, you can safely return rethrow the error.
  * The workflow engine will handle the interruption automatically.
  *
  * @example
  * ```typescript
+ * import { MemFlow } from '@hotmeshio/hotmesh';
+ *
  * try {
  *   await someWorkflowOperation();
  * } catch (error) {
  *   // Check if this is a HotMesh interruption
- *   if (didInterrupt(error)) {
- *     // Rethrow the error if HotMesh interruption
+ *   if (MemFlow.workflow.didInterrupt(error)) {
+ *     // Rethrow the error
  *     throw error;
  *   }
  *   // Handle actual error

package/build/services/memflow/workflow/interruption.js

@@ -4,19 +4,21 @@ exports.didInterrupt = void 0;
 const errors_1 = require("../../../modules/errors");
 /**
  * Checks if an error is a HotMesh reserved error type that indicates
- * a workflow interruption rather than a true error condition.
+ * a HotMesh interruption rather than a true error condition.
  *
- * When this returns true, you can safely return from your workflow function.
+ * When this returns true, you can safely return rethrow the error.
  * The workflow engine will handle the interruption automatically.
  *
  * @example
  * ```typescript
+ * import { MemFlow } from '@hotmeshio/hotmesh';
+ *
  * try {
  *   await someWorkflowOperation();
  * } catch (error) {
  *   // Check if this is a HotMesh interruption
- *   if (didInterrupt(error)) {
- *     // Rethrow the error if HotMesh interruption
+ *   if (MemFlow.workflow.didInterrupt(error)) {
+ *     // Rethrow the error
  *     throw error;
  *   }
  *   // Handle actual error

package/build/services/memflow/workflow/waitFor.js

@@ -50,6 +50,7 @@ async function waitFor(signalId) {
     };
     interruptionRegistry.push(interruptionMessage);
     await (0, common_1.sleepImmediate)();
+    //if you are seeing this error in the logs, you might have forgotten to `await waitFor(...)`
     throw new common_1.MemFlowWaitForError(interruptionMessage);
 }
 exports.waitFor = waitFor;

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

@@ -19,5 +19,15 @@ declare abstract class SearchService<ClientProvider extends ProviderClient> {
     abstract incrementFieldByFloat(key: string, field: string, increment: number): Promise<number>;
     abstract sendQuery(query: any): Promise<any>;
     abstract sendIndexedQuery(index: string, query: any[]): Promise<any>;
+    abstract findEntities(entity: string, conditions: Record<string, any>, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<any[]>;
+    abstract findEntityById(entity: string, id: string): Promise<any>;
+    abstract findEntitiesByCondition(entity: string, field: string, value: any, operator?: '=' | '!=' | '>' | '<' | '>=' | '<=' | 'LIKE' | 'IN', options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<any[]>;
+    abstract createEntityIndex(entity: string, field: string, indexType?: 'btree' | 'gin' | 'gist'): Promise<void>;
 }
 export { SearchService };

package/build/services/search/providers/postgres/postgres.d.ts

@@ -21,5 +21,17 @@ declare class PostgresSearchService extends SearchService<PostgresClientType & P
      * assume aggregation type query
      */
     sendIndexedQuery(type: string, queryParams?: any[]): Promise<any[]>;
+    findEntities(entity: string, conditions: Record<string, any>, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<any[]>;
+    findEntityById(entity: string, id: string): Promise<any>;
+    findEntitiesByCondition(entity: string, field: string, value: any, operator?: '=' | '!=' | '>' | '<' | '>=' | '<=' | 'LIKE' | 'IN', options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<any[]>;
+    createEntityIndex(entity: string, field: string, indexType?: 'btree' | 'gin' | 'gist'): Promise<void>;
+    private mongoToSqlOperator;
+    private inferType;
 }
 export { PostgresSearchService };

package/build/services/search/providers/postgres/postgres.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PostgresSearchService = void 0;
 const index_1 = require("../../index");
 const kvsql_1 = require("../../../store/providers/postgres/kvsql");
+const key_1 = require("../../../../modules/key");
 class PostgresSearchService extends index_1.SearchService {
     transact() {
         return this.storeClient.transact();
@@ -145,5 +146,213 @@ class PostgresSearchService extends index_1.SearchService {
             throw error;
         }
     }
+    // Entity querying methods for JSONB/SQL operations
+    async findEntities(entity, conditions, options) {
+        try {
+            const schemaName = this.searchClient.safeName(this.appId);
+            const tableName = `${schemaName}.${this.searchClient.safeName('jobs')}`;
+            // Build WHERE conditions from the conditions object
+            const whereConditions = [`entity = $1`];
+            const params = [entity];
+            let paramIndex = 2;
+            for (const [key, value] of Object.entries(conditions)) {
+                if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                    // Handle MongoDB-style operators like { $gte: 18 }
+                    for (const [op, opValue] of Object.entries(value)) {
+                        const sqlOp = this.mongoToSqlOperator(op);
+                        whereConditions.push(`(context->>'${key}')::${this.inferType(opValue)} ${sqlOp} $${paramIndex}`);
+                        params.push(opValue);
+                        paramIndex++;
+                    }
+                }
+                else {
+                    // Simple equality
+                    whereConditions.push(`context->>'${key}' = $${paramIndex}`);
+                    params.push(String(value));
+                    paramIndex++;
+                }
+            }
+            let sql = `
+        SELECT key, context, status
+        FROM ${tableName}
+        WHERE ${whereConditions.join(' AND ')}
+        ORDER BY created_at DESC
+      `;
+            if (options?.limit) {
+                sql += ` LIMIT $${paramIndex}`;
+                params.push(options.limit);
+                paramIndex++;
+            }
+            if (options?.offset) {
+                sql += ` OFFSET $${paramIndex}`;
+                params.push(options.offset);
+            }
+            const result = await this.pgClient.query(sql, params);
+            return result.rows.map(row => ({
+                key: row.key,
+                context: typeof row.context === 'string' ? JSON.parse(row.context || '{}') : (row.context || {}),
+                status: row.status,
+            }));
+        }
+        catch (error) {
+            this.logger.error(`postgres-find-entities-error`, { entity, conditions, error });
+            throw error;
+        }
+    }
+    async findEntityById(entity, id) {
+        try {
+            const schemaName = this.searchClient.safeName(this.appId);
+            const tableName = `${schemaName}.${this.searchClient.safeName('jobs')}`;
+            // Use KeyService to mint the job state key
+            const fullKey = key_1.KeyService.mintKey(key_1.HMNS, key_1.KeyType.JOB_STATE, {
+                appId: this.appId,
+                jobId: id
+            });
+            const sql = `
+        SELECT key, context, status, entity
+        FROM ${tableName}
+        WHERE entity = $1 AND key = $2
+        LIMIT 1
+      `;
+            const result = await this.pgClient.query(sql, [entity, fullKey]);
+            if (result.rows.length === 0) {
+                return null;
+            }
+            const row = result.rows[0];
+            return {
+                key: row.key,
+                context: typeof row.context === 'string' ? JSON.parse(row.context || '{}') : (row.context || {}),
+                status: row.status,
+            };
+        }
+        catch (error) {
+            this.logger.error(`postgres-find-entity-by-id-error`, { entity, id, error });
+            throw error;
+        }
+    }
+    async findEntitiesByCondition(entity, field, value, operator = '=', options) {
+        try {
+            const schemaName = this.searchClient.safeName(this.appId);
+            const tableName = `${schemaName}.${this.searchClient.safeName('jobs')}`;
+            const params = [entity];
+            let whereCondition;
+            let paramIndex = 2;
+            if (operator === 'IN') {
+                // Handle IN operator with arrays
+                const placeholders = Array.isArray(value)
+                    ? value.map(() => `$${paramIndex++}`).join(',')
+                    : `$${paramIndex++}`;
+                whereCondition = `context->>'${field}' IN (${placeholders})`;
+                if (Array.isArray(value)) {
+                    params.push(...value);
+                }
+                else {
+                    params.push(value);
+                }
+            }
+            else if (operator === 'LIKE') {
+                whereCondition = `context->>'${field}' LIKE $${paramIndex}`;
+                params.push(value);
+                paramIndex++;
+            }
+            else {
+                // Handle numeric/comparison operators
+                const valueType = this.inferType(value);
+                whereCondition = `(context->>'${field}')::${valueType} ${operator} $${paramIndex}`;
+                params.push(value);
+                paramIndex++;
+            }
+            let sql = `
+        SELECT key, context, status
+        FROM ${tableName}
+        WHERE entity = $1 AND ${whereCondition}
+        ORDER BY created_at DESC
+      `;
+            if (options?.limit) {
+                sql += ` LIMIT $${paramIndex}`;
+                params.push(options.limit);
+                paramIndex++;
+            }
+            if (options?.offset) {
+                sql += ` OFFSET $${paramIndex}`;
+                params.push(options.offset);
+            }
+            const result = await this.pgClient.query(sql, params);
+            return result.rows.map(row => ({
+                key: row.key,
+                context: typeof row.context === 'string' ? JSON.parse(row.context || '{}') : (row.context || {}),
+                status: row.status,
+            }));
+        }
+        catch (error) {
+            this.logger.error(`postgres-find-entities-by-condition-error`, {
+                entity, field, value, operator, error
+            });
+            throw error;
+        }
+    }
+    async createEntityIndex(entity, field, indexType = 'btree') {
+        try {
+            const schemaName = this.searchClient.safeName(this.appId);
+            const tableName = `${schemaName}.${this.searchClient.safeName('jobs')}`;
+            const indexName = `idx_${this.appId}_${entity}_${field}`.replace(/[^a-zA-Z0-9_]/g, '_');
+            let sql;
+            if (indexType === 'gin') {
+                // GIN index for JSONB operations
+                sql = `
+          CREATE INDEX IF NOT EXISTS ${indexName}
+          ON ${tableName} USING gin (context jsonb_path_ops)
+          WHERE entity = '${entity}'
+        `;
+            }
+            else if (indexType === 'gist') {
+                // GiST index for specific field
+                sql = `
+          CREATE EXTENSION IF NOT EXISTS pg_trgm;
+          CREATE INDEX IF NOT EXISTS ${indexName}
+          ON ${tableName} USING gist ((context->>'${field}') gist_trgm_ops)
+          WHERE entity = '${entity}'
+        `;
+            }
+            else {
+                // B-tree index for specific field
+                sql = `
+          CREATE INDEX IF NOT EXISTS ${indexName}
+          ON ${tableName} USING btree ((context->>'${field}'))
+          WHERE entity = '${entity}'
+        `;
+            }
+            await this.pgClient.query(sql);
+            this.logger.info(`postgres-entity-index-created`, { entity, field, indexType, indexName });
+        }
+        catch (error) {
+            this.logger.error(`postgres-create-entity-index-error`, {
+                entity, field, indexType, error
+            });
+            throw error;
+        }
+    }
+    // Helper methods for entity operations
+    mongoToSqlOperator(mongoOp) {
+        const mapping = {
+            '$eq': '=',
+            '$ne': '!=',
+            '$gt': '>',
+            '$gte': '>=',
+            '$lt': '<',
+            '$lte': '<=',
+            '$in': 'IN',
+        };
+        return mapping[mongoOp] || '=';
+    }
+    inferType(value) {
+        if (typeof value === 'number') {
+            return Number.isInteger(value) ? 'integer' : 'numeric';
+        }
+        if (typeof value === 'boolean') {
+            return 'boolean';
+        }
+        return 'text';
+    }
 }
 exports.PostgresSearchService = PostgresSearchService;

package/build/services/search/providers/redis/ioredis.d.ts

@@ -15,5 +15,9 @@ declare class IORedisSearchService extends SearchService<IORedisClientType> {
     incrementFieldByFloat(key: string, field: string, increment: number): Promise<number>;
     sendQuery(...query: [string, ...string[]]): Promise<any>;
     sendIndexedQuery(index: string, query: string[]): Promise<string[]>;
+    findEntities(): Promise<any[]>;
+    findEntityById(): Promise<any>;
+    findEntitiesByCondition(): Promise<any[]>;
+    createEntityIndex(): Promise<void>;
 }
 export { IORedisSearchService };

package/build/services/search/providers/redis/ioredis.js

@@ -117,5 +117,18 @@ class IORedisSearchService extends index_1.SearchService {
             throw error;
         }
     }
+    // Entity methods - not implemented for Redis (postgres-specific JSONB operations)
+    async findEntities() {
+        throw new Error('Entity findEntities not supported in Redis - use PostgreSQL');
+    }
+    async findEntityById() {
+        throw new Error('Entity findEntityById not supported in Redis - use PostgreSQL');
+    }
+    async findEntitiesByCondition() {
+        throw new Error('Entity findEntitiesByCondition not supported in Redis - use PostgreSQL');
+    }
+    async createEntityIndex() {
+        throw new Error('Entity createEntityIndex not supported in Redis - use PostgreSQL');
+    }
 }
 exports.IORedisSearchService = IORedisSearchService;

package/build/services/search/providers/redis/redis.d.ts

@@ -15,5 +15,9 @@ declare class RedisSearchService extends SearchService<RedisRedisClientType> {
     incrementFieldByFloat(key: string, field: string, increment: number): Promise<number>;
     sendQuery(...query: any[]): Promise<any>;
     sendIndexedQuery(index: string, query: string[]): Promise<string[]>;
+    findEntities(): Promise<any[]>;
+    findEntityById(): Promise<any>;
+    findEntitiesByCondition(): Promise<any[]>;
+    createEntityIndex(): Promise<void>;
 }
 export { RedisSearchService };

package/build/services/search/providers/redis/redis.js

@@ -130,5 +130,18 @@ class RedisSearchService extends index_1.SearchService {
             throw error;
         }
     }
+    // Entity methods - not implemented for Redis (postgres-specific JSONB operations)
+    async findEntities() {
+        throw new Error('Entity findEntities not supported in Redis - use PostgreSQL');
+    }
+    async findEntityById() {
+        throw new Error('Entity findEntityById not supported in Redis - use PostgreSQL');
+    }
+    async findEntitiesByCondition() {
+        throw new Error('Entity findEntitiesByCondition not supported in Redis - use PostgreSQL');
+    }
+    async createEntityIndex() {
+        throw new Error('Entity createEntityIndex not supported in Redis - use PostgreSQL');
+    }
 }
 exports.RedisSearchService = RedisSearchService;