Durable Entities Support

.github/workflows/codeql.yml

@@ -62,5 +62,3 @@ jobs:
       uses: github/codeql-action/analyze@v3
       with:
         category: "/language:${{matrix.language}}"
-
-        category: "/language:${{matrix.language}}"

README.md

@@ -93,7 +93,34 @@ const orchestrator: TOrchestrator = async function* (ctx: OrchestrationContext,
 As an aside, you'll also notice that the example orchestration above works with custom business objects. Support for custom business objects includes support for custom classes, custom data classes, and named tuples. Serialization and deserialization of these objects is handled automatically by the SDK.
 
 You can find the full sample [here](./examples/human_interaction.ts).
+### Durable Entities (Stateful Actors)
 
+Durable entities provide a way to manage small pieces of state with a simple object-oriented programming model:
+
+```typescript
+import { TaskEntity, EntityInstanceId } from "durabletask-js";
+
+// Define an entity by extending TaskEntity
+class CounterEntity extends TaskEntity<{ value: number }> {
+  add(amount: number): number {
+    this.state.value += amount;
+    return this.state.value;
+  }
+
+  protected initializeState() {
+    return { value: 0 };
+  }
+}
+
+// From an orchestration, call the entity
+const orchestrator: TOrchestrator = async function* (ctx: OrchestrationContext): any {
+  const entityId = new EntityInstanceId("Counter", "myCounter");
+  const value: number = yield* ctx.entities.callEntity(entityId, "add", 5);
+  return value;
+};
+```
+
+You can find full entity samples [here](./examples/hello-world/entity-counter.ts) and [here](./examples/hello-world/entity-orchestration.ts).
 ## Feature overview
 
 The following features are currently supported:
@@ -122,6 +149,10 @@ Orchestrations can wait for external events using the `wait_for_external_event`
 
 Orchestrations can be continued as new using the `continue_as_new` API. This API allows an orchestration to restart itself from scratch, optionally with a new input.
 
+### Durable Entities
+
+Durable entities are stateful objects that can be accessed from orchestrations or directly from clients. They support operations that can read/modify state, and multiple entities can be locked together for atomic cross-entity transactions. See the detailed section below for more information.
+
 ### Suspend, resume, and terminate
 
 Orchestrations can be suspended using the `suspend_orchestration` client API and will remain suspended until resumed using the `resume_orchestration` client API. A suspended orchestration will stop processing new events, but will continue to buffer any that happen to arrive until resumed, ensuring that no data is lost. An orchestration can also be terminated using the `terminate_orchestration` client API. Terminated orchestrations will stop processing new events and will discard any buffered events.
@@ -130,6 +161,120 @@ Orchestrations can be suspended using the `suspend_orchestration` client API and
 
 Orchestrations can specify retry policies for activities and sub-orchestrations. These policies control how many times and how frequently an activity or sub-orchestration will be retried in the event of a transient error.
 
+### Durable Entities
+
+Durable entities are stateful objects that can be accessed and manipulated from orchestrations or directly from clients. Entities provide a way to manage small pieces of state that need to be accessed and updated reliably.
+
+#### Defining an Entity
+
+Entities are defined by extending the `TaskEntity` class:
+
+```typescript
+import { TaskEntity } from "durabletask-js";
+
+interface CounterState {
+  value: number;
+}
+
+class CounterEntity extends TaskEntity<CounterState> {
+  // Operations are just methods on the class
+  add(amount: number): number {
+    this.state.value += amount;
+    return this.state.value;
+  }
+
+  get(): number {
+    return this.state.value;
+  }
+
+  reset(): void {
+    this.state.value = 0;
+  }
+
+  // Required: Initialize the entity state
+  protected initializeState(): CounterState {
+    return { value: 0 };
+  }
+}
+
+// Register with the worker
+worker.addEntity("Counter", () => new CounterEntity());
+```
+
+#### Accessing Entities from a Client
+
+Entities can be signaled (fire-and-forget) or queried from a client:
+
+```typescript
+import { TaskHubGrpcClient, EntityInstanceId } from "durabletask-js";
+
+const client = new TaskHubGrpcClient("localhost:4001");
+const entityId = new EntityInstanceId("Counter", "myCounter");
+
+// Signal an operation (fire-and-forget)
+await client.signalEntity(entityId, "add", 5);
+
+// Get the entity state
+const response = await client.getEntity<CounterState>(entityId);
+console.log(`Current value: ${response.state?.value}`);
+```
+
+#### Calling Entities from Orchestrations
+
+Orchestrations can call entities and wait for results:
+
+```typescript
+const orchestrator: TOrchestrator = async function* (ctx: OrchestrationContext): any {
+  const entityId = new EntityInstanceId("Counter", "myCounter");
+
+  // Call entity and wait for result
+  const currentValue: number = yield* ctx.entities.callEntity(entityId, "get");
+
+  // Signal entity (fire-and-forget)
+  ctx.entities.signalEntity(entityId, "add", 10);
+
+  return currentValue;
+};
+```
+
+#### Entity Locking (Critical Sections)
+
+Multiple entities can be locked together for atomic operations:
+
+```typescript
+const transferOrchestration: TOrchestrator = async function* (
+  ctx: OrchestrationContext,
+  input: { from: string; to: string; amount: number }
+): any {
+  const fromEntity = new EntityInstanceId("Account", input.from);
+  const toEntity = new EntityInstanceId("Account", input.to);
+
+  // Lock both entities atomically (sorted to prevent deadlocks)
+  const lock = yield* ctx.entities.lockEntities(fromEntity, toEntity);
+
+  try {
+    const fromBalance: number = yield* ctx.entities.callEntity(fromEntity, "getBalance");
+    if (fromBalance >= input.amount) {
+      yield* ctx.entities.callEntity(fromEntity, "withdraw", input.amount);
+      yield* ctx.entities.callEntity(toEntity, "deposit", input.amount);
+    }
+  } finally {
+    lock.release();
+  }
+};
+```
+
+#### Entity Management
+
+Clean up empty or unused entities:
+
+```typescript
+// Clean up entities that have been empty for 30 days
+await client.cleanEntityStorage({ removeEmptyEntities: true });
+```
+
+You can find full entity examples [here](./examples/hello-world/entity-counter.ts) and [here](./examples/hello-world/entity-orchestration.ts).
+
 ## Getting Started
 
 ### Prerequisites

examples/hello-world/README.md

@@ -36,6 +36,8 @@ In some cases, the sample may require command-line parameters or user inputs. In
 - [Activity sequence](./activity-sequence.ts): Orchestration that schedules three activity calls in a sequence.
 - [Fan-out/fan-in](./fanout-fanin.ts): Orchestration that schedules a dynamic number of activity calls in parallel, waits for all of them to complete, and then performs an aggregation on the results.
 - [Azure Managed DTS](./azure-managed-dts.ts): Demonstrates integration with Azure Managed Durable Task Scheduler (DTS) using the portable SDK with Azure authentication.
+- [Entity Counter](./entity-counter.ts): A simple Counter entity demonstrating durable entities - defining entity state, operations, and accessing entities from a client.
+- [Entity Orchestration](./entity-orchestration.ts): Demonstrates calling and locking entities from orchestrations, including a bank transfer scenario with atomic cross-entity transactions.
 
 ## Running the Azure Managed DTS example
 

examples/hello-world/entity-counter.ts

@@ -0,0 +1,157 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+/**
+ * This example demonstrates a simple Counter entity using Durable Entities.
+ *
+ * Durable Entities are stateful objects that can be addressed by a unique ID.
+ * They process operations one at a time, ensuring consistency without explicit locks.
+ *
+ * Key concepts demonstrated:
+ * - Defining an entity with TaskEntity<TState>
+ * - Entity operations (add, get, reset)
+ * - Signaling entities from a client (fire-and-forget)
+ * - Getting entity state from a client
+ */
+
+import { TaskHubGrpcClient } from "../../packages/durabletask-js/src/client/client";
+import { TaskHubGrpcWorker } from "../../packages/durabletask-js/src/worker/task-hub-grpc-worker";
+import { TaskEntity, EntityInstanceId } from "../../packages/durabletask-js/src/entities";
+
+// ============================================================================
+// Step 1: Define the entity state type
+// ============================================================================
+
+/**
+ * The state type for our Counter entity.
+ */
+interface CounterState {
+  value: number;
+}
+
+// ============================================================================
+// Step 2: Define the Counter entity class
+// ============================================================================
+
+/**
+ * A simple counter entity that can be incremented, decremented, and reset.
+ *
+ * Operations are defined as public methods on the class.
+ * The operation name is the method name (case-insensitive).
+ */
+class CounterEntity extends TaskEntity<CounterState> {
+  /**
+   * Adds a value to the counter.
+   * @param amount - The amount to add (can be negative to subtract).
+   * @returns The new counter value.
+   */
+  add(amount: number): number {
+    this.state.value += amount;
+    return this.state.value;
+  }
+
+  /**
+   * Gets the current counter value.
+   * @returns The current value.
+   */
+  get(): number {
+    return this.state.value;
+  }
+
+  /**
+   * Resets the counter to zero.
+   */
+  reset(): void {
+    this.state.value = 0;
+  }
+
+  /**
+   * Initializes the entity state when it's first created.
+   * @returns The initial state with value = 0.
+   */
+  protected initializeState(): CounterState {
+    return { value: 0 };
+  }
+}
+
+// ============================================================================
+// Step 3: Main - Set up worker and client, then interact with the entity
+// ============================================================================
+
+(async () => {
+  const grpcServerAddress = "localhost:4001";
+  const client = new TaskHubGrpcClient(grpcServerAddress);
+  const worker = new TaskHubGrpcWorker(grpcServerAddress);
+
+  // Register the entity with the worker
+  worker.addEntity("Counter", () => new CounterEntity());
+
+  try {
+    await worker.start();
+    console.log("Worker started successfully");
+
+    // Create an entity ID - this identifies a specific counter instance
+    const counterId = new EntityInstanceId("Counter", "my-counter");
+
+    // ========================================================================
+    // Signal the entity (fire-and-forget operations)
+    // ========================================================================
+
+    console.log("\n--- Signaling entity operations ---");
+
+    // Signal the counter to add 5 (doesn't wait for result)
+    await client.signalEntity(counterId, "add", 5);
+    console.log("Signaled: add(5)");
+
+    // Signal the counter to add 3
+    await client.signalEntity(counterId, "add", 3);
+    console.log("Signaled: add(3)");
+
+    // Signal the counter to add -2 (subtract)
+    await client.signalEntity(counterId, "add", -2);
+    console.log("Signaled: add(-2)");
+
+    // Wait a moment for signals to be processed
+    await new Promise((resolve) => setTimeout(resolve, 2000));
+
+    // ========================================================================
+    // Get the entity state
+    // ========================================================================
+
+    console.log("\n--- Getting entity state ---");
+
+    const metadata = await client.getEntity<CounterState>(counterId);
+    if (metadata.exists) {
+      console.log(`Counter value: ${metadata.state?.value}`);
+      console.log(`Last modified: ${metadata.lastModifiedTime}`);
+    } else {
+      console.log("Entity does not exist yet");
+    }
+
+    // ========================================================================
+    // Reset and verify
+    // ========================================================================
+
+    console.log("\n--- Resetting counter ---");
+
+    await client.signalEntity(counterId, "reset");
+    console.log("Signaled: reset()");
+
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+
+    const afterReset = await client.getEntity<CounterState>(counterId);
+    console.log(`Counter value after reset: ${afterReset.state?.value}`);
+
+    // ========================================================================
+    // Clean up
+    // ========================================================================
+
+    console.log("\n--- Cleaning up ---");
+    await worker.stop();
+    console.log("Worker stopped");
+
+  } catch (error) {
+    console.error("Error:", error);
+    await worker.stop();
+  }
+})();