Temporal Ts Entity Pattern

How to Use

Environment Context Gathering

Before implementing, clarify the following with the user:

1. Where is Temporal running? Local dev server (temporal server start-dev), self-hosted cluster, or Temporal Cloud?
2. If not local, what is the full Temporal server URL? (e.g., my-namespace.abc123.tmprl.cloud:7233)
3. Is ingress set up for the Temporal HTTP API? This matters for external clients, web UIs, and codec servers connecting to the cluster.
4. What task queue name will the worker listen on?
5. What namespace? Default is "default" for local dev.

These affect the Client and Worker connection configuration.

Overview

The entity pattern models a single long-lived entity (user, order, device, subscription) as one Temporal Workflow Execution. The workflow:

• Receives external input via Signals (fire-and-forget) or Updates (request-response)
• Exposes state via Queries (read-only, synchronous)
• Periodically calls continueAsNew to reset event history and avoid hitting the 50K event limit
• Handles cancellation gracefully with cleanup logic

The workflow ID typically maps 1:1 to the entity ID (e.g., user-abc123).

Quick Reference

Implementation Patterns

Pattern 1: Core Entity Workflow (from official docs)

This is the canonical pattern. It collects updates via a signal, processes them, and calls continueAsNew after a fixed number of iterations.

import {
  defineSignal,
  setHandler,
  condition,
  continueAsNew,
  isCancellation,
  CancellationScope,
  proxyActivities,
} from '@temporalio/workflow';
import type * as activities from './activities';

const { processUpdate, setup, cleanup } = proxyActivities<typeof activities>({
  startToCloseTimeout: '5 minutes',
});

// --- Type definitions ---
interface EntityInput {
  entityId: string;
  config: Record<string, unknown>;
}
interface EntityUpdate {
  action: string;
  payload: unknown;
}

// --- Signal definition (exported so clients can import it) ---
export const updateSignal = defineSignal<[EntityUpdate]>('update');

const MAX_ITERATIONS = 1;

export async function entityWorkflow(
  input: EntityInput,
  isNew = true,
): Promise<void> {
  try {
    const pendingUpdates: EntityUpdate[] = [];
    setHandler(updateSignal, (updateCommand) => {
      pendingUpdates.push(updateCommand);
    });

    if (isNew) {
      await setup(input);
    }

    for (let iteration = 1; iteration <= MAX_ITERATIONS; ++iteration) {
      // Wait up to 1 day for updates; ensures continueAsNew eventually fires
      await condition(() => pendingUpdates.length > 0, '1 day');

      // Drain all pending updates
      while (pendingUpdates.length) {
        const update = pendingUpdates.shift()!;
        await processUpdate(update);
      }
    }
  } catch (err) {
    if (isCancellation(err)) {
      await CancellationScope.nonCancellable(async () => {
        await cleanup();
      });
    }
    throw err;
  }
  // Continue as new, passing isNew=false to skip setup
  await continueAsNew<typeof entityWorkflow>(input, false);
}

Key points:

• MAX_ITERATIONS controls how many update cycles before continueAsNew. Set to 1 for frequent resets, higher for fewer.
• isNew flag differentiates first run from continued runs (skip setup on continue).
• condition() with a timeout ensures the workflow does not block forever.
• Pending updates are drained in a while loop before continuing.

Pattern 2: Entity with Signals, Queries, and Updates

A richer entity that exposes queryable state and supports validated updates.

import {
  defineSignal,
  defineQuery,
  defineUpdate,
  setHandler,
  condition,
  continueAsNew,
  proxyActivities,
  ApplicationFailure,
} from '@temporalio/workflow';
import type * as activities from './activities';

const { applyChange, notifyOwner } = proxyActivities<typeof activities>({
  startToCloseTimeout: '5 minutes',
  retry: { maximumAttempts: 3 },
});

// --- Definitions (export for client use) ---
export const addItemSignal = defineSignal<[string]>('addItem');
export const getStateQuery = defineQuery<EntityState>('getState');
export const setPriorityUpdate = defineUpdate<string, [number]>('setPriority');

interface EntityState {
  items: string[];
  priority: number;
  status: string;
}

const MAX_ITERATIONS = 500;

export async function managedEntityWorkflow(
  entityId: string,
  initialState?: Partial<EntityState>,
): Promise<void> {
  // --- Mutable state ---
  const state: EntityState = {
    items: initialState?.items ?? [],
    priority: initialState?.priority ?? 1,
    status: initialState?.status ?? 'active',
  };

  // --- Signal handler (fire-and-forget, sync only) ---
  setHandler(addItemSignal, (item: string) => {
    state.items.push(item);
  });

  // --- Query handler (read-only, must be sync) ---
  setHandler(getStateQuery, () => ({ ...state }));

  // --- Update handler (can be async, can return values) ---
  setHandler(
    setPriorityUpdate,
    async (newPriority: number) => {
      const old = state.priority;
      state.priority = newPriority;
      await notifyOwner(`Priority changed from ${old} to ${newPriority}`);
      return `Priority set to ${newPriority}`;
    },
    {
      validator: (newPriority: number) => {
        if (newPriority < 1 || newPriority > 10) {
          throw ApplicationFailure.nonRetryable(
            'Priority must be between 1 and 10'
          );
        }
      },
    },
  );

  // --- Main loop ---
  for (let i = 0; i < MAX_ITERATIONS; i++) {
    const hasNewItems = await condition(
      () => state.items.length > 0,
      '1 hour',
    );
    if (hasNewItems) {
      const batch = state.items.splice(0, state.items.length);
      for (const item of batch) {
        await applyChange({ entityId, item });
      }
    }
  }

  // Pass current state forward across continueAsNew
  await continueAsNew<typeof managedEntityWorkflow>(entityId, state);
}

Pattern 3: Client-Side Interaction

import { Client } from '@temporalio/client';
import {
  managedEntityWorkflow,
  addItemSignal,
  getStateQuery,
  setPriorityUpdate,
} from './workflows';

const client = new Client(/* connection config */);

// --- Start the entity workflow ---
const handle = await client.workflow.start(managedEntityWorkflow, {
  workflowId: `entity-${entityId}`,  // deterministic ID = entity ID
  taskQueue: 'my-task-queue',
  args: [entityId],
});

// --- Signal (fire-and-forget) ---
await handle.signal(addItemSignal, 'new-item');

// --- Query (read-only, immediate response) ---
const state = await handle.query(getStateQuery);

// --- Update (request-response, can await result) ---
const result = await handle.executeUpdate(setPriorityUpdate, {
  args: [5],
  waitForStage: 'COMPLETED',
});

// --- Or start update and poll later ---
const updateHandle = await handle.startUpdate(setPriorityUpdate, {
  args: [7],
  updateId: 'priority-update-001',
  waitForStage: 'ACCEPTED',
});
const updateResult = await updateHandle.result();

Pattern 4: Worker Setup

import { Worker } from '@temporalio/worker';
import * as activities from './activities';

async function run() {
  const worker = await Worker.create({
    workflowsPath: require.resolve('./workflows'),
    activities,
    taskQueue: 'my-task-queue',
    // For Temporal Cloud:
    // connection: { address: 'my-ns.abc123.tmprl.cloud:7233', tls: { ... } }
  });
  await worker.run();
}

run().catch((err) => {
  console.error(err);
  process.exit(1);
});

Common Mistakes

1. Forgetting to drain pending signals before continueAsNew

Wrong: Calling continueAsNew immediately without processing buffered signals. Those signals are lost.

Right: Use a while (pendingUpdates.length) loop to process all buffered signals before continueAsNew.

2. Blocking forever without a condition timeout

Wrong: await condition(() => pendingUpdates.length > 0) with no timeout. The workflow never calls continueAsNew if no signals arrive, and history grows unbounded.

Right: Always pass a timeout: await condition(() => pendingUpdates.length > 0, '1 day').

3. Running side effects in signal handlers

Wrong: Calling activities or doing I/O inside a signal handler. Signal handlers must be synchronous.

Right: Buffer the signal data, then process it in the main workflow loop where you can await activities.

4. Not passing state through continueAsNew

Wrong: await continueAsNew<typeof myWorkflow>(entityId) -- loses all accumulated state.

Right: await continueAsNew<typeof myWorkflow>(entityId, currentState) and accept that state as an argument.

5. Using a non-deterministic workflow ID

Wrong: Random workflow IDs for entities. You cannot find or signal the workflow later.

Right: Use a deterministic ID: workflowId: 'entity-${entityId}'. Temporal deduplicates by workflow ID.

6. Making query handlers async or mutating state in them

Wrong: setHandler(myQuery, async () => { state.x = 1; return state; }). Queries must be synchronous and read-only.

Right: setHandler(myQuery, () => ({ ...state })). Return a copy, no mutations, no await.

7. Not handling cancellation

Wrong: No try/catch around the main loop. Cancellation throws CancelledFailure and skips cleanup.

Right: Wrap in try/catch, check isCancellation(err), run cleanup in CancellationScope.nonCancellable.

Debugging Tips

1. View event history in the Temporal Web UI or via tctl workflow show -w <workflowId>. Look for WorkflowExecutionContinuedAsNew events to confirm the pattern is cycling.

2. Check history length with handle.describe() -- if historyLength is growing past a few thousand, your MAX_ITERATIONS may be too high or continueAsNew is not firing.

3. Signal delivery issues? Signals are buffered. If the workflow is stuck in an activity, signals queue up and are delivered when the workflow yields. Check that your condition() or main loop actually processes them.

4. Update validation failures show up as ApplicationFailure on the client side. Check the validator function logic.

5. Worker not picking up tasks? Verify the taskQueue matches between client start options and worker config. Check the worker logs for registration messages.

6. Workflow replaying unexpectedly? This is normal after worker restarts. Ensure your workflow code is deterministic (no Date.now(), no Math.random(), no direct I/O).

7. Use temporal workflow list (Temporal CLI) to see running entity workflows and their status.

Further Reading

If this skill does not answer your question, use Context7 to search /temporalio/sdk-typescript or /temporalio/samples-typescript for more details.