Skip to content

Commit b0c1eb0

Browse files
CopilotCopilot
authored
Restructure entity examples as standalone apps with DTS emulator support (#83)
1 parent 3fb9198 commit b0c1eb0

9 files changed

Lines changed: 533 additions & 58 deletions

File tree

‎examples/README.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# Durable Task JavaScript SDK - Examples
2+
3+
This directory contains examples demonstrating various features of the Durable Task JavaScript SDK.
4+
5+
## Example Applications
6+
7+
Each example is a standalone application with its own README and can be run independently.
8+
9+
### Basic Orchestration Examples
10+
11+
Located in `hello-world/`:
12+
13+
- **[Activity Sequence](./hello-world/activity-sequence.ts)**: Basic orchestration that calls three activities in sequence.
14+
- **[Fan-out/Fan-in](./hello-world/fanout-fanin.ts)**: Orchestration that schedules multiple activities in parallel and aggregates results.
15+
- **[Human Interaction](./hello-world/human_interaction.ts)**: Demonstrates waiting for external events in orchestrations.
16+
17+
### Durable Entities Examples
18+
19+
Durable Entities are stateful objects with built-in concurrency control:
20+
21+
- **[Entity Counter](./entity-counter/)**: Simple counter entity demonstrating basic entity operations, signaling, and state management.
22+
- **[Entity Orchestration](./entity-orchestration/)**: Bank transfer scenario using entity locking for atomic cross-entity operations.
23+
24+
### Azure Integration Examples
25+
26+
- **[Azure Managed DTS](./azure-managed/)**: Integration with Azure Managed Durable Task Scheduler using Azure authentication.
27+
- **[Azure Managed DTS (Simple)](./azure-managed-dts.ts)**: Simplified version showing Azure DTS connection setup.
28+
29+
## Prerequisites
30+
31+
Examples require a Durable Task-compatible backend. Choose one:
32+
33+
### Option 1: DTS Emulator (Recommended for Testing)
34+
35+
The DTS Emulator is ideal for local development and testing:
36+
37+
```bash
38+
docker run --name dts-emulator -i -p 8080:8080 -d --rm mcr.microsoft.com/dts/dts-emulator:latest
39+
```
40+
41+
Most standalone examples can run against the emulator using:
42+
43+
```bash
44+
cd examples/entity-counter
45+
npm run start:emulator
46+
```
47+
48+
### Option 2: Local Sidecar
49+
50+
Install and run locally (requires Go 1.18+):
51+
52+
```bash
53+
# Install Dapr CLI (includes Durable Task sidecar)
54+
https://docs.dapr.io/getting-started/install-dapr-cli/
55+
56+
# Or build from source
57+
git clone https://github.com/microsoft/durabletask-go
58+
cd durabletask-go
59+
go run . start --backend Emulator
60+
```
61+
62+
The sidecar runs on `localhost:4001` by default.
63+
64+
### Option 3: Unofficial Sidecar Docker Image
65+
66+
For quick local development:
67+
68+
```bash
69+
docker run \
70+
--name durabletask-sidecar -d --rm \
71+
-p 4001:4001 \
72+
--env 'DURABLETASK_SIDECAR_LOGLEVEL=Debug' \
73+
kaibocai/durabletask-sidecar:latest start \
74+
--backend Emulator
75+
```
76+
77+
## Running Examples
78+
79+
### Standalone Applications (Recommended)
80+
81+
Standalone applications include `entity-counter` and `entity-orchestration`. Each has its own `package.json`:
82+
83+
```bash
84+
cd examples/entity-counter
85+
npm run start:emulator # Run against DTS emulator
86+
# OR
87+
npm run start # Run against local sidecar on localhost:4001
88+
```
89+
90+
See individual README files for detailed instructions.
91+
92+
### Single-File Examples
93+
94+
Basic orchestration examples in `hello-world/` can be run directly:
95+
96+
```bash
97+
npm run example ./examples/hello-world/activity-sequence.ts
98+
```
99+
100+
## Testing Against DTS Emulator
101+
102+
All entity examples are designed to work with the DTS emulator:
103+
104+
1. Start the DTS emulator:
105+
```bash
106+
docker run --name dts-emulator -i -p 8080:8080 -d --rm mcr.microsoft.com/dts/dts-emulator:latest
107+
```
108+
109+
2. Run the example:
110+
```bash
111+
cd examples/entity-counter
112+
npm run start:emulator
113+
```
114+
115+
The emulator provides a clean, isolated environment for testing without requiring external dependencies.
116+
117+
## Azure Managed DTS
118+
119+
For production scenarios with Azure, see the [Azure Managed DTS example](./azure-managed/) which demonstrates:
120+
- Connection string configuration
121+
- Azure authentication with DefaultAzureCredential
122+
- Environment-based configuration
123+
124+
## Documentation
125+
126+
For more information about Durable Task concepts:
127+
128+
- **Orchestrations**: Workflow definitions that coordinate activities
129+
- **Activities**: Units of work executed by orchestrations
130+
- **Entities**: Stateful actors with automatic concurrency control
131+
- **Entity Locking**: Critical sections for atomic multi-entity operations
132+
133+
See the main [README](../README.md) for comprehensive documentation.

‎examples/TESTING.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# Testing Entity Examples Against DTS Emulator
2+
3+
This guide explains how to test the entity examples (`entity-counter` and `entity-orchestration`) against the DTS emulator.
4+
5+
## Prerequisites
6+
7+
1. Docker installed and running
8+
2. Node.js 22+ installed (as specified in package.json)
9+
3. Dependencies installed: `npm install` in the repository root
10+
11+
## Step 1: Start the DTS Emulator
12+
13+
```bash
14+
docker run --name dts-emulator -i -p 8080:8080 -d --rm mcr.microsoft.com/dts/dts-emulator:latest
15+
```
16+
17+
Wait a few seconds for the emulator to be ready.
18+
19+
## Step 2: Test entity-counter Example
20+
21+
```bash
22+
cd examples/entity-counter
23+
npm run start:emulator
24+
```
25+
26+
### Expected Output
27+
28+
```
29+
Connecting to endpoint: localhost:8080, taskHub: default
30+
Worker started successfully
31+
32+
--- Signaling entity operations ---
33+
Signaled: add(5)
34+
Signaled: add(3)
35+
Signaled: add(-2)
36+
37+
--- Getting entity state ---
38+
Counter value: 6
39+
Last modified: [timestamp]
40+
41+
--- Resetting counter ---
42+
Signaled: reset()
43+
Counter value after reset: 0
44+
45+
--- Cleaning up ---
46+
Worker stopped
47+
```
48+
49+
## Step 3: Test entity-orchestration Example
50+
51+
```bash
52+
cd examples/entity-orchestration
53+
npm run start:emulator
54+
```
55+
56+
### Expected Output
57+
58+
```
59+
Connecting to endpoint: localhost:8080, taskHub: default
60+
Worker started successfully
61+
62+
--- Initializing accounts ---
63+
Alice balance: 1000
64+
Bob balance: 500
65+
66+
--- Running transfer orchestration ---
67+
Transfer orchestration started: [instance-id]
68+
In critical section: true
69+
Locked entities: BankAccount@alice, BankAccount@bob
70+
From account balance: 1000
71+
To account balance: 500
72+
Transfer completed: {"success":true,"fromBalance":750,"toBalance":750,"message":"Transferred 250 from alice to bob"}
73+
74+
--- Final balances ---
75+
Alice balance: 750
76+
Bob balance: 750
77+
78+
--- Cleaning up ---
79+
Worker stopped
80+
```
81+
82+
## Step 4: Clean Up
83+
84+
Stop the DTS emulator:
85+
86+
```bash
87+
docker stop dts-emulator
88+
```
89+
90+
## Alternative: Test Against Local Sidecar
91+
92+
If you prefer to test against a local sidecar instead of the emulator:
93+
94+
1. Start the sidecar on `localhost:4001` (using Dapr CLI or durabletask-go)
95+
2. Run the examples with the default start script:
96+
97+
```bash
98+
cd examples/entity-counter
99+
npm run start
100+
```
101+
102+
## Troubleshooting
103+
104+
### "Cannot find module" errors
105+
106+
Make sure dependencies are installed:
107+
```bash
108+
cd /path/to/durabletask-js
109+
npm install
110+
```
111+
112+
### "ts-node: command not found"
113+
114+
The `ts-node` package should be installed as a dev dependency. Run `npm install` in the repository root.
115+
116+
### Emulator connection errors
117+
118+
- Verify the emulator is running: `docker ps | grep dts-emulator`
119+
- Check logs: `docker logs dts-emulator`
120+
- Ensure port 8080 is not in use by another process
121+
122+
### Worker fails to start
123+
124+
Check that the packages are built:
125+
```bash
126+
npm run build
127+
```
128+
129+
## Validation Script
130+
131+
A validation script is available to check the structure:
132+
133+
```bash
134+
bash /tmp/validate_examples.sh
135+
```
136+
137+
This verifies:
138+
- Example directory structure
139+
- package.json scripts
140+
- Environment variable support
141+
- Required imports and builders

‎examples/entity-counter/README.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Entity Counter Example
2+
3+
This example demonstrates a simple Counter entity using Durable Entities.
4+
5+
## What are Durable Entities?
6+
7+
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.
8+
9+
## Key Concepts
10+
11+
This example demonstrates:
12+
- Defining an entity with `TaskEntity<TState>`
13+
- Entity operations (add, get, reset)
14+
- Signaling entities from a client (fire-and-forget)
15+
- Getting entity state from a client
16+
17+
## Prerequisites
18+
19+
You need a Durable Task-compatible backend. Choose one:
20+
21+
### Option 1: DTS Emulator (Recommended for testing)
22+
23+
```bash
24+
docker run --name dts-emulator -i -p 8080:8080 -d --rm mcr.microsoft.com/dts/dts-emulator:latest
25+
```
26+
27+
### Option 2: Local Sidecar
28+
29+
Install and run the [Durable Task Sidecar](https://github.com/microsoft/durabletask-go) or [Dapr CLI](https://docs.dapr.io/getting-started/install-dapr-cli/) on `localhost:4001`.
30+
31+
## Running the Example
32+
33+
### With DTS Emulator
34+
35+
```bash
36+
npm run start:emulator
37+
```
38+
39+
### With Local Sidecar
40+
41+
```bash
42+
npm run start
43+
```
44+
45+
## Expected Output
46+
47+
```
48+
Connecting to endpoint: localhost:8080, taskHub: default
49+
Worker started successfully
50+
51+
--- Signaling entity operations ---
52+
Signaled: add(5)
53+
Signaled: add(3)
54+
Signaled: add(-2)
55+
56+
--- Getting entity state ---
57+
Counter value: 6
58+
Last modified: [timestamp]
59+
60+
--- Resetting counter ---
61+
Signaled: reset()
62+
Counter value after reset: 0
63+
64+
--- Cleaning up ---
65+
Worker stopped
66+
```

0 commit comments

Comments
 (0)