Function entity

Returns an Entity session handle for interacting with the workflow's structured JSON document storage. Unlike search() (flat HASH key-value pairs), entity() provides a JSONB document store with deep merge, append, and path-based get operations.

Each call produces a unique session ID tied to the deterministic execution counter, ensuring correct replay behavior.

Examples

import { Durable } from '@hotmeshio/hotmesh';

export async function userProfileWorkflow(userId: string): Promise<UserProfile> {
  const entity = await Durable.workflow.entity();

  // Initialize a structured document
  await entity.set({
    user: { id: userId, status: 'active' },
    preferences: { theme: 'dark', locale: 'en-US' },
  });

  // Deep merge: adds name without overwriting existing fields
  await entity.merge({ user: { name: 'Alice', email: 'alice@example.com' } });
  // user is now: { id: userId, status: 'active', name: 'Alice', email: '...' }

  // Append to an array
  await entity.set({ user: { tags: ['premium'] } });
  await entity.append({ user: { tags: ['verified'] } });
  // user.tags is now: ['premium', 'verified']

  // Read a nested path
  const user = await entity.get('user');
  return user as UserProfile;
}
Copy

// Accumulate state across activities
export async function pipelineWorkflow(input: string): Promise<PipelineResult> {
  const entity = await Durable.workflow.entity();
  const { step1, step2, step3 } = Durable.workflow.proxyActivities<typeof activities>();

  const r1 = await step1(input);
  await entity.merge({ pipeline: { step1: r1 } });

  const r2 = await step2(r1);
  await entity.merge({ pipeline: { step2: r2 } });

  const r3 = await step3(r2);
  await entity.merge({ pipeline: { step3: r3 } });

  return await entity.get('pipeline') as PipelineResult;
}
Copy

Not available with workerCredentials. This method writes directly to the jobs table (JSONB context column), bypassing the SECURITY DEFINER stored procedures that scoped worker roles are restricted to. Workers connecting with workerCredentials will receive a permission error. Use entity() only in workflows running with full database credentials.