@hotmeshio/hotmesh
Version:
Permanent-Memory Workflows & AI Agents
308 lines (307 loc) • 8.97 kB
TypeScript
import { HotMesh } from '../hotmesh';
import { SearchService } from '../search';
/**
* The Entity module provides methods for reading and writing
* JSONB data to a workflow's entity. The instance methods
* exposed by this class are available for use from within
* a running workflow.
*
* @example
* ```typescript
* //entityWorkflow.ts
* import { workflow } from '@hotmeshio/hotmesh';
*
* export async function entityExample(): Promise<void> {
* const entity = await workflow.entity();
* await entity.set({ user: { id: 123 } });
* await entity.merge({ user: { name: "John" } });
* const user = await entity.get("user");
* // user = { id: 123, name: "John" }
* }
* ```
*/
export declare class Entity {
/**
* @private
*/
jobId: string;
/**
* @private
*/
searchSessionId: string;
/**
* @private
*/
searchSessionIndex: number;
/**
* @private
*/
hotMeshClient: HotMesh;
/**
* @private
*/
search: SearchService<any> | null;
/**
* @private
*/
workflowDimension: string;
/**
* @private
*/
constructor(workflowId: string, hotMeshClient: HotMesh, searchSessionId: string);
/**
* increments the index to return a unique search session guid when
* calling any method that produces side effects (changes the value)
* @private
*/
getSearchSessionGuid(): string;
/**
* Sets the entire entity object. This replaces any existing entity.
*
* @example
* const entity = await workflow.entity();
* await entity.set({ user: { id: 123, name: "John" } });
*/
set<T>(value: T): Promise<T>;
/**
* Deep merges the provided object with the existing entity
*
* @example
* const entity = await workflow.entity();
* await entity.merge({ user: { email: "john@example.com" } });
*/
merge<T>(value: T): Promise<T>;
/**
* Gets a value from the entity by path
*
* @example
* const entity = await workflow.entity();
* const user = await entity.get("user");
* const email = await entity.get("user.email");
*/
get<T>(path?: string): Promise<T>;
/**
* Deletes a value from the entity by path
*
* @example
* const entity = await workflow.entity();
* await entity.delete("user.email");
*/
delete(path: string): Promise<any>;
/**
* Appends a value to an array at the specified path
*
* @example
* const entity = await workflow.entity();
* await entity.append("items", { id: 1, name: "New Item" });
*/
append(path: string, value: any): Promise<any[]>;
/**
* Prepends a value to an array at the specified path
*
* @example
* const entity = await workflow.entity();
* await entity.prepend("items", { id: 0, name: "First Item" });
*/
prepend(path: string, value: any): Promise<any[]>;
/**
* Removes an item from an array at the specified path and index
*
* @example
* const entity = await workflow.entity();
* await entity.remove("items", 0); // Remove first item
*/
remove(path: string, index: number): Promise<any[]>;
/**
* Increments a numeric value at the specified path
*
* @example
* const entity = await workflow.entity();
* await entity.increment("counter", 5);
*/
increment(path: string, value?: number): Promise<number>;
/**
* Toggles a boolean value at the specified path
*
* @example
* const entity = await workflow.entity();
* await entity.toggle("settings.enabled");
*/
toggle(path: string): Promise<boolean>;
/**
* Sets a value at the specified path only if it doesn't already exist
*
* @example
* const entity = await workflow.entity();
* await entity.setIfNotExists("user.id", 123);
*/
setIfNotExists(path: string, value: any): Promise<any>;
/**
* 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);
* ```
*/
static createIndex(entity: string, field: string, hotMeshClient: HotMesh, indexType?: 'gin'): Promise<void>;
}