@hotmeshio/hotmesh 0.5.1 → 0.5.2

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;

package/build/services/store/providers/postgres/kvsql.d.ts

@@ -2,7 +2,7 @@ import { KeyStoreParams } from '../../../../types/hotmesh';
 import { PostgresClientType } from '../../../../types/postgres';
 import { ProviderTransaction } from '../../../../types/provider';
 import { stringModule } from './kvtypes/string';
-import { hashModule } from './kvtypes/hash';
+import { hashModule } from './kvtypes/hash/index';
 import { listModule } from './kvtypes/list';
 import { zsetModule } from './kvtypes/zset';
 /**
@@ -30,8 +30,8 @@ export declare class KVSQL {
      */
     tableForKey(key: string, stats_type?: 'hash' | 'sorted_set' | 'list'): string;
     safeName(input: string, prefix?: string): string;
-    set: (key: string, value: string, options?: import("../../../../types/provider").SetOptions, multi?: ProviderTransaction) => Promise<boolean>;
-    _set: (key: string, value: string, options?: import("../../../../types/provider").SetOptions) => {
+    set: (key: string, value: string, options?: import("./kvtypes/hash/index").SetOptions, multi?: ProviderTransaction) => Promise<boolean>;
+    _set: (key: string, value: string, options?: import("./kvtypes/hash/index").SetOptions) => {
         sql: string;
         params: any[];
     };
@@ -47,51 +47,27 @@ export declare class KVSQL {
     };
     setnx: (key: string, value: string, multi?: ProviderTransaction) => Promise<boolean>;
     setnxex: (key: string, value: string, delay: number, multi?: ProviderTransaction) => Promise<boolean>;
-    hset: (key: string, fields: Record<string, string>, options?: import("../../../../types/provider").HSetOptions, multi?: ProviderTransaction) => Promise<any>;
-    _hset: (key: string, fields: Record<string, string>, options?: import("../../../../types/provider").HSetOptions) => {
-        sql: string;
-        params: any[];
-    };
+    hset: (key: string, fields: Record<string, string>, options?: import("./kvtypes/hash/index").HSetOptions, multi?: any) => Promise<any>;
+    _hset: (key: string, fields: Record<string, string>, options?: import("./kvtypes/hash/index").HSetOptions) => import("./kvtypes/hash/types").SqlResult;
     hsetnx: (key: string, field: string, value: string, multi?: ProviderTransaction, entity?: string) => Promise<number>;
     hget: (key: string, field: string, multi?: ProviderTransaction) => Promise<string>;
-    _hget: (key: string, field: string) => {
-        sql: string;
-        params: any[];
-    };
+    _hget: (key: string, field: string) => import("./kvtypes/hash/types").SqlResult;
     hdel: (key: string, fields: string[], multi?: unknown) => Promise<number>;
-    _hdel: (key: string, fields: string[]) => {
-        sql: string;
-        params: any[];
-    };
+    _hdel: (key: string, fields: string[]) => import("./kvtypes/hash/types").SqlResult;
     hmget: (key: string, fields: string[], multi?: ProviderTransaction) => Promise<string[]>;
-    _hmget: (key: string, fields: string[]) => {
-        sql: string;
-        params: any[];
-    };
+    _hmget: (key: string, fields: string[]) => import("./kvtypes/hash/types").SqlResult;
     hgetall: (key: string, multi?: ProviderTransaction) => Promise<Record<string, string>>;
     hincrbyfloat: (key: string, field: string, increment: number, multi?: ProviderTransaction) => Promise<number>;
-    _hincrbyfloat: (key: string, field: string, increment: number) => {
-        sql: string;
-        params: any[];
-    };
-    hscan: (key: string, cursor: string, count?: number, pattern?: string, multi?: ProviderTransaction) => Promise<import("../../../../types/provider").HScanResult>;
-    _hscan: (key: string, cursor: string, count: number, pattern?: string) => {
-        sql: string;
-        params: any[];
-    };
+    _hincrbyfloat: (key: string, field: string, increment: number) => import("./kvtypes/hash/types").SqlResult;
+    hscan: (key: string, cursor: string, count?: number, pattern?: string, multi?: ProviderTransaction) => Promise<import("./kvtypes/hash/index").HScanResult>;
+    _hscan: (key: string, cursor: string, count: number, pattern?: string) => import("./kvtypes/hash/types").SqlResult;
     expire: (key: string, seconds: number, multi?: ProviderTransaction) => Promise<boolean>;
-    _expire: (key: string, seconds: number) => {
-        sql: string;
-        params: any[];
-    };
+    _expire: (key: string, seconds: number) => import("./kvtypes/hash/types").SqlResult;
     scan: (cursor: number, count?: number, pattern?: string, multi?: ProviderTransaction) => Promise<{
         cursor: number;
         keys: string[];
     }>;
-    _scan: (cursor: number, count: number, pattern?: string) => {
-        sql: string;
-        params: any[];
-    };
+    _scan: (cursor: number, count: number, pattern?: string) => import("./kvtypes/hash/types").SqlResult;
     lrange: (key: string, start: number, end: number, multi?: ProviderTransaction) => Promise<string[]>;
     _lrange: (key: string, start: number, end: number) => {
         sql: string;

package/build/services/store/providers/postgres/kvsql.js

@@ -4,7 +4,7 @@ exports.KVSQL = void 0;
 const key_1 = require("../../../../modules/key");
 const kvtransaction_1 = require("./kvtransaction");
 const string_1 = require("./kvtypes/string");
-const hash_1 = require("./kvtypes/hash");
+const index_1 = require("./kvtypes/hash/index");
 const list_1 = require("./kvtypes/list");
 const zset_1 = require("./kvtypes/zset");
 /**
@@ -72,7 +72,7 @@ class KVSQL {
         this.pgClient = pgClient;
         this.namespace = namespace;
         this.appId = appId;
-        this.hash = (0, hash_1.hashModule)(this);
+        this.hash = (0, index_1.hashModule)(this);
         this.list = (0, list_1.listModule)(this);
         this.zset = (0, zset_1.zsetModule)(this);
         this.string = (0, string_1.stringModule)(this);

package/build/services/store/providers/postgres/kvtypes/hash/basic.d.ts

@@ -0,0 +1,16 @@
+import { HashContext, SqlResult, HSetOptions, ProviderTransaction } from './types';
+export declare function createBasicOperations(context: HashContext['context']): {
+    hsetnx(key: string, field: string, value: string, multi?: ProviderTransaction, entity?: string): Promise<number>;
+    hset(key: string, fields: Record<string, string>, options?: HSetOptions, multi?: ProviderTransaction): Promise<number | any>;
+    hget(key: string, field: string, multi?: ProviderTransaction): Promise<string | null>;
+    hdel(key: string, fields: string[], multi?: unknown): Promise<number>;
+    hmget(key: string, fields: string[], multi?: ProviderTransaction): Promise<(string | null)[]>;
+    hgetall(key: string, multi?: ProviderTransaction): Promise<Record<string, string>>;
+    hincrbyfloat(key: string, field: string, increment: number, multi?: ProviderTransaction): Promise<number>;
+};
+export declare function _hset(context: HashContext['context'], key: string, fields: Record<string, string>, options?: HSetOptions): SqlResult;
+export declare function _hget(context: HashContext['context'], key: string, field: string): SqlResult;
+export declare function _hdel(context: HashContext['context'], key: string, fields: string[]): SqlResult;
+export declare function _hmget(context: HashContext['context'], key: string, fields: string[]): SqlResult;
+export declare function _hgetall(context: HashContext['context'], key: string): SqlResult;
+export declare function _hincrbyfloat(context: HashContext['context'], key: string, field: string, increment: number): SqlResult;