Durable Entities Support

[YunchuWang]

This pull request introduces comprehensive support and documentation for Durable Entities (stateful actors) in the SDK, including new sample code and expanded README sections. Durable Entities allow users to define, access, and manipulate persistent state objects both from orchestrations and directly from clients, supporting atomic operations and entity locking for critical sections. The changes include new example files, updates to documentation, and minor dependency additions.

Durable Entities Feature and Documentation:

• Added detailed Durable Entities documentation to README.md, including how to define entities, access them from clients and orchestrations, perform entity locking for atomic operations, and clean up entities. Also added usage examples and links to new sample files. [1] [2] [3]
• Added a new section to the hello-world examples README describing the new entity samples: entity-counter.ts and entity-orchestration.ts.

New Durable Entities Sample Code:

• Added examples/hello-world/entity-counter.ts, demonstrating how to define a simple counter entity, perform operations, and interact with it from a client.
• Added examples/hello-world/entity-orchestration.ts, showing how to use entities within orchestrations, including entity locking for atomic bank transfers and signaling entities.

SDK and Dependency Updates:

• Updated the client import in packages/durabletask-js/src/client/client.ts to include Int32Value from the protobuf wrappers, likely in support of new entity features.

Other Minor Changes:

• Removed a duplicate category line from the CodeQL workflow YAML.

[Copilot]

Pull request overview

Adds Durable Entities (stateful actors) support to the durabletask-js SDK, including orchestration-side entity APIs, worker-side entity execution, client-side entity management APIs, plus documentation and samples.

Changes:

• Added entity runtime primitives (entity IDs, entity base class/operation context/state types, locking feature, failure types).
• Extended worker and orchestration executor to process entity work items and entity-related history events; added client APIs for signaling/querying/cleaning entities and paging results.
• Added extensive unit tests and documentation/samples for Durable Entities.

Reviewed changes

Copilot reviewed 46 out of 47 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
test/e2e-azuremanaged/orchestration.spec.ts	Updates DTS E2E test setup to support either emulator or real scheduler via connection string.
packages/durabletask-js/test/worker-entity.spec.ts	Adds worker tests for entity registration APIs.
packages/durabletask-js/test/task-entity.spec.ts	Adds tests for TaskEntity dispatch/state/implicit delete behavior.
packages/durabletask-js/test/task-entity-state.spec.ts	Adds tests documenting expected state semantics (including deletion).
packages/durabletask-js/test/task-entity-operation.spec.ts	Adds tests for operation interface shape/semantics.
packages/durabletask-js/test/task-entity-context.spec.ts	Adds tests for entity context APIs and options types.
packages/durabletask-js/test/signal-entity-options.spec.ts	Adds tests for signal/call entity options types.
packages/durabletask-js/test/registry.spec.ts	Adds tests for entity registration/lookups in Registry.
packages/durabletask-js/test/orchestration-entity-feature.spec.ts	Adds tests for orchestration-side entity feature behavior (signal/call).
packages/durabletask-js/test/entity-query.spec.ts	Adds tests for entity query normalization utilities.
packages/durabletask-js/test/entity-operation-failed-exception.spec.ts	Adds tests for entity failure conversion + exception message formatting.
packages/durabletask-js/test/entity-operation-events.spec.ts	Adds tests for handling entity operation completed/failed history events in executor.
packages/durabletask-js/test/entity-metadata.spec.ts	Adds tests for entity metadata creation utilities.
packages/durabletask-js/test/entity-locking.spec.ts	Adds tests for critical sections (locking) semantics and unlock behavior.
packages/durabletask-js/test/entity-instance-id.spec.ts	Adds tests for entity instance ID parsing/serialization/equality.
packages/durabletask-js/test/entity-executor.spec.ts	Adds tests for worker-side entity execution shim (batch ops, rollback, actions).
packages/durabletask-js/test/entity-client.spec.ts	Adds tests validating proto conversion for client entity APIs.
packages/durabletask-js/test/clean-entity-storage.spec.ts	Adds tests for clean entity storage request/result types.
packages/durabletask-js/src/worker/task-hub-grpc-worker.ts	Adds entity registration methods and executes entity work items (v1 and v2).
packages/durabletask-js/src/worker/runtime-orchestration-context.ts	Adds orchestration entity feature implementation and deterministic request IDs.
packages/durabletask-js/src/worker/registry.ts	Extends registry to track entity factories with case-insensitive lookup.
packages/durabletask-js/src/worker/orchestration-executor.ts	Handles entity-related history events and wires executionId into context.
packages/durabletask-js/src/worker/entity-executor.ts	Implements entity batch execution shim with transactional rollback and action capture.
packages/durabletask-js/src/utils/pb-helper.util.ts	Adds helpers to build entity-related orchestrator actions (signal/call/lock/unlock).
packages/durabletask-js/src/utils/async-pageable.ts	Adds AsyncPageable<T> helper for paged entity queries.
packages/durabletask-js/src/task/context/orchestration-context.ts	Adds entities feature to orchestration context API surface.
packages/durabletask-js/src/index.ts	Exposes new entity APIs and AsyncPageable from the package entrypoint.
packages/durabletask-js/src/entities/task-entity.ts	Adds TaskEntity base class and ITaskEntity/EntityFactory types.
packages/durabletask-js/src/entities/task-entity-state.ts	Adds entity state interface.
packages/durabletask-js/src/entities/task-entity-operation.ts	Adds entity operation interface.
packages/durabletask-js/src/entities/task-entity-context.ts	Adds entity context interface for signaling/scheduling orchestrations from entities.
packages/durabletask-js/src/entities/signal-entity-options.ts	Adds options types for signaling/calling entities.
packages/durabletask-js/src/entities/orchestration-entity-feature.ts	Adds orchestration-side entity feature interfaces (call/signal/lock).
packages/durabletask-js/src/entities/index.ts	Adds entities barrel exports.
packages/durabletask-js/src/entities/entity-query.ts	Adds entity query model + normalization helpers.
packages/durabletask-js/src/entities/entity-operation-failed-exception.ts	Adds failure details conversion + exception type.
packages/durabletask-js/src/entities/entity-metadata.ts	Adds entity metadata model + constructors.
packages/durabletask-js/src/entities/entity-instance-id.ts	Adds entity ID parsing/formatting utilities.
packages/durabletask-js/src/entities/clean-entity-storage.ts	Adds clean entity storage request/result model + defaults.
packages/durabletask-js/src/client/client.ts	Adds entity client APIs (signal/get/query/clean) and paged iteration.
package-lock.json	Updates lockfile metadata for dependencies.
examples/hello-world/entity-orchestration.ts	Adds orchestration + locking example using entities.
examples/hello-world/entity-counter.ts	Adds basic entity example (counter) and client interaction.
examples/hello-world/README.md	Documents the new entity samples.
README.md	Adds Durable Entities documentation and usage examples.
.github/workflows/codeql.yml	Removes duplicated category entry.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[torosent]

@copilot, the examples are not clear. split them to proper apps. They should be tested against the dts-emulator. Make sure to update the readme in the examples folder

[Copilot]

@torosent I've opened a new pull request, #83, to work on those changes. Once the pull request is ready, I'll request review from you.