Restructure entity examples as standalone apps with DTS emulator support

examples/README.md

@@ -0,0 +1,133 @@
+# Durable Task JavaScript SDK - Examples
+
+This directory contains examples demonstrating various features of the Durable Task JavaScript SDK.
+
+## Example Applications
+
+Each example is a standalone application with its own README and can be run independently.
+
+### Basic Orchestration Examples
+
+Located in `hello-world/`:
+
+- **[Activity Sequence](./hello-world/activity-sequence.ts)**: Basic orchestration that calls three activities in sequence.
+- **[Fan-out/Fan-in](./hello-world/fanout-fanin.ts)**: Orchestration that schedules multiple activities in parallel and aggregates results.
+- **[Human Interaction](./hello-world/human_interaction.ts)**: Demonstrates waiting for external events in orchestrations.
+
+### Durable Entities Examples
+
+Durable Entities are stateful objects with built-in concurrency control:
+
+- **[Entity Counter](./entity-counter/)**: Simple counter entity demonstrating basic entity operations, signaling, and state management.
+- **[Entity Orchestration](./entity-orchestration/)**: Bank transfer scenario using entity locking for atomic cross-entity operations.
+
+### Azure Integration Examples
+
+- **[Azure Managed DTS](./azure-managed/)**: Integration with Azure Managed Durable Task Scheduler using Azure authentication.
+- **[Azure Managed DTS (Simple)](./azure-managed-dts.ts)**: Simplified version showing Azure DTS connection setup.
+
+## Prerequisites
+
+Examples require a Durable Task-compatible backend. Choose one:
+
+### Option 1: DTS Emulator (Recommended for Testing)
+
+The DTS Emulator is ideal for local development and testing:
+
+```bash
+docker run --name dts-emulator -i -p 8080:8080 -d --rm mcr.microsoft.com/dts/dts-emulator:latest
+```
+
+Most standalone examples can run against the emulator using:
+
+```bash
+cd examples/entity-counter
+npm run start:emulator
+```
+
+### Option 2: Local Sidecar
+
+Install and run locally (requires Go 1.18+):
+
+```bash
+# Install Dapr CLI (includes Durable Task sidecar)
+https://docs.dapr.io/getting-started/install-dapr-cli/
+
+# Or build from source
+git clone https://github.com/microsoft/durabletask-go
+cd durabletask-go
+go run . start --backend Emulator
+```
+
+The sidecar runs on `localhost:4001` by default.
+
+### Option 3: Unofficial Sidecar Docker Image
+
+For quick local development:
+
+```bash
+docker run \
+    --name durabletask-sidecar -d --rm \
+    -p 4001:4001 \
+    --env 'DURABLETASK_SIDECAR_LOGLEVEL=Debug' \
+    kaibocai/durabletask-sidecar:latest start \
+    --backend Emulator
+```
+
+## Running Examples
+
+### Standalone Applications (Recommended)
+
+Standalone applications include `entity-counter` and `entity-orchestration`. Each has its own `package.json`:
+
+```bash
+cd examples/entity-counter
+npm run start:emulator  # Run against DTS emulator
+# OR
+npm run start           # Run against local sidecar on localhost:4001
+```
+
+See individual README files for detailed instructions.
+
+### Single-File Examples
+
+Basic orchestration examples in `hello-world/` can be run directly:
+
+```bash
+npm run example ./examples/hello-world/activity-sequence.ts
+```
+
+## Testing Against DTS Emulator
+
+All entity examples are designed to work with the DTS emulator:
+
+1. Start the DTS emulator:
+   ```bash
+   docker run --name dts-emulator -i -p 8080:8080 -d --rm mcr.microsoft.com/dts/dts-emulator:latest
+   ```
+
+2. Run the example:
+   ```bash
+   cd examples/entity-counter
+   npm run start:emulator
+   ```
+
+The emulator provides a clean, isolated environment for testing without requiring external dependencies.
+
+## Azure Managed DTS
+
+For production scenarios with Azure, see the [Azure Managed DTS example](./azure-managed/) which demonstrates:
+- Connection string configuration
+- Azure authentication with DefaultAzureCredential
+- Environment-based configuration
+
+## Documentation
+
+For more information about Durable Task concepts:
+
+- **Orchestrations**: Workflow definitions that coordinate activities
+- **Activities**: Units of work executed by orchestrations
+- **Entities**: Stateful actors with automatic concurrency control
+- **Entity Locking**: Critical sections for atomic multi-entity operations
+
+See the main [README](../README.md) for comprehensive documentation.

examples/TESTING.md

@@ -0,0 +1,141 @@
+# Testing Entity Examples Against DTS Emulator
+
+This guide explains how to test the entity examples (`entity-counter` and `entity-orchestration`) against the DTS emulator.
+
+## Prerequisites
+
+1. Docker installed and running
+2. Node.js 22+ installed (as specified in package.json)
+3. Dependencies installed: `npm install` in the repository root
+
+## Step 1: Start the DTS Emulator
+
+```bash
+docker run --name dts-emulator -i -p 8080:8080 -d --rm mcr.microsoft.com/dts/dts-emulator:latest
+```
+
+Wait a few seconds for the emulator to be ready.
+
+## Step 2: Test entity-counter Example
+
+```bash
+cd examples/entity-counter
+npm run start:emulator
+```
+
+### Expected Output
+
+```
+Connecting to endpoint: localhost:8080, taskHub: default
+Worker started successfully
+
+--- Signaling entity operations ---
+Signaled: add(5)
+Signaled: add(3)
+Signaled: add(-2)
+
+--- Getting entity state ---
+Counter value: 6
+Last modified: [timestamp]
+
+--- Resetting counter ---
+Signaled: reset()
+Counter value after reset: 0
+
+--- Cleaning up ---
+Worker stopped
+```
+
+## Step 3: Test entity-orchestration Example
+
+```bash
+cd examples/entity-orchestration
+npm run start:emulator
+```
+
+### Expected Output
+
+```
+Connecting to endpoint: localhost:8080, taskHub: default
+Worker started successfully
+
+--- Initializing accounts ---
+Alice balance: 1000
+Bob balance: 500
+
+--- Running transfer orchestration ---
+Transfer orchestration started: [instance-id]
+In critical section: true
+Locked entities: BankAccount@alice, BankAccount@bob
+From account balance: 1000
+To account balance: 500
+Transfer completed: {"success":true,"fromBalance":750,"toBalance":750,"message":"Transferred 250 from alice to bob"}
+
+--- Final balances ---
+Alice balance: 750
+Bob balance: 750
+
+--- Cleaning up ---
+Worker stopped
+```
+
+## Step 4: Clean Up
+
+Stop the DTS emulator:
+
+```bash
+docker stop dts-emulator
+```
+
+## Alternative: Test Against Local Sidecar
+
+If you prefer to test against a local sidecar instead of the emulator:
+
+1. Start the sidecar on `localhost:4001` (using Dapr CLI or durabletask-go)
+2. Run the examples with the default start script:
+
+```bash
+cd examples/entity-counter
+npm run start
+```
+
+## Troubleshooting
+
+### "Cannot find module" errors
+
+Make sure dependencies are installed:
+```bash
+cd /path/to/durabletask-js
+npm install
+```
+
+### "ts-node: command not found"
+
+The `ts-node` package should be installed as a dev dependency. Run `npm install` in the repository root.
+
+### Emulator connection errors
+
+- Verify the emulator is running: `docker ps | grep dts-emulator`
+- Check logs: `docker logs dts-emulator`
+- Ensure port 8080 is not in use by another process
+
+### Worker fails to start
+
+Check that the packages are built:
+```bash
+npm run build
+```
+
+## Validation Script
+
+A validation script is available to check the structure:
+
+```bash
+bash /tmp/validate_examples.sh
+```
+
+This verifies:
+- Example directory structure
+- package.json scripts
+- Environment variable support
+- Required imports and builders

examples/entity-counter/README.md

@@ -0,0 +1,66 @@
+# Entity Counter Example
+
+This example demonstrates a simple Counter entity using Durable Entities.
+
+## What are 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
+
+This example demonstrates:
+- 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
+
+## Prerequisites
+
+You need a Durable Task-compatible backend. Choose one:
+
+### Option 1: DTS Emulator (Recommended for testing)
+
+```bash
+docker run --name dts-emulator -i -p 8080:8080 -d --rm mcr.microsoft.com/dts/dts-emulator:latest
+```
+
+### Option 2: Local Sidecar
+
+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`.
+
+## Running the Example
+
+### With DTS Emulator
+
+```bash
+npm run start:emulator
+```
+
+### With Local Sidecar
+
+```bash
+npm run start
+```
+
+## Expected Output
+
+```
+Connecting to endpoint: localhost:8080, taskHub: default
+Worker started successfully
+
+--- Signaling entity operations ---
+Signaled: add(5)
+Signaled: add(3)
+Signaled: add(-2)
+
+--- Getting entity state ---
+Counter value: 6
+Last modified: [timestamp]
+
+--- Resetting counter ---
+Signaled: reset()
+Counter value after reset: 0
+
+--- Cleaning up ---
+Worker stopped
+```