Export History

[YunchuWang]

Summary

What changed?

Add a new @microsoft/durabletask-js-export-history package that enables exporting orchestration instance history to Azure Blob Storage. This is a JavaScript/TypeScript port of the Export History feature from durabletask-dotnet.

New package: packages/durabletask-js-export-history/

• Entity (export-job.ts): Durable entity that tracks export job lifecycle (Pending → Active → Completed/Failed) with checkpoint support and state transitions
• Orchestrators:
  • export-job-orchestrator.ts: Main orchestrator that lists terminal instances, exports their history in batches with retry logic (exponential backoff), commits checkpoints, and marks completion/failure
  • execute-export-job-operation-orchestrator.ts: Wrapper orchestrator that creates the entity and starts the export job
• Activities:
  • export-instance-history-activity.ts: Fetches instance history via gRPC, serializes to JSONL/JSON format, compresses with gzip, and uploads to Azure Blob Storage
  • list-terminal-instances-activity.ts: Lists orchestration instances in terminal states within a time window
• Client (export-history-client.ts): ExportHistoryClient and ExportHistoryJobClient classes for creating, querying, deleting, and describing export jobs
• Builders (use-export-history.ts): useExportHistoryWorker() helper to register all export history orchestrators, activities, and entities on a worker
• Models: Full set of TypeScript types for export configuration, job state, destinations, formats, filters, checkpoints, and failures
• Errors: Custom error classes (ExportJobClientValidationError, ExportJobInvalidTransitionError)
• Constants: Named constants for orchestrators, activities, and entities

Test coverage:

• 54 unit tests across 6 test suites (builders, constants, entity, errors, models, list-terminal-instances-activity)
• 18 E2E tests (test/e2e-azuremanaged/export-history.spec.ts) covering:
  • Entity lifecycle (create, query, delete, auto-generated jobId)
  • Export execution & blob verification (N-instance export, empty window, JSONL.GZ content, JSON format, multi-step orchestrations, blob isolation, failed orchestrations, mixed status, full history event sequence matching)
  • Configuration validation (defaults, missing connectionString/containerName)
  • Diagnostics (orchestrator start verification)
• E2E tests are gated behind EXPORT_HISTORY_E2E=1 env var (skipped in CI — DTS emulator lacks entity support)

Other changes:

• jest.config.js: Added module name mapping for @microsoft/durabletask-js-export-history
• CHANGELOG.md: Removed duplicate v0.2.0 entries (branch was based on pre-v0.2.0)
• Version alignment: durabletask-js and durabletask-js-azuremanaged package versions set to 0.1.0-beta.1

Why is this change needed?

Enables users to export durable orchestration instance history to Azure Blob Storage for auditing, analytics, and long-term retention. This fills a gap in the JS SDK where the equivalent feature already exists in the .NET SDK (durabletask-dotnet).

Issues / work items

• Related: Export History feature parity with durabletask-dotnet

---

Project checklist

• Release notes are not required for the next release
  • Otherwise: Notes added to CHANGELOG.md
• Backport is not required
  • Otherwise: Backport tracked by issue/PR #issue_or_pr
• All required tests have been added/updated (unit tests, E2E tests)
• Breaking change?
  • No breaking changes. This is a new additive package.

---

AI-assisted code disclosure (required)

Was an AI tool used? (select one)

• No
• Yes, AI helped write parts of this PR (e.g., GitHub Copilot)
• Yes, an AI agent generated most of this PR

If AI was used:

• Tool(s): GitHub Copilot (Claude)
• AI-assisted areas/files: All files in packages/durabletask-js-export-history/, test/e2e-azuremanaged/export-history.spec.ts, jest.config.js
• What you changed after AI output: Reviewed and iterated on orchestrator logic, entity state transitions, error handling, and E2E test correctness

AI verification (required if AI was used):

• I understand the code and can explain it
• I verified referenced APIs/types exist and are correct
• I reviewed edge cases/failure paths (timeouts, retries, cancellation, exceptions)
• I reviewed concurrency/async behavior
• I checked for unintended breaking or behavior changes

---

Testing

Automated tests

• Unit tests: 54 passed, 0 failed (6 test suites)
• E2E tests: 18 passed, 0 failed (requires EXPORT_HISTORY_E2E=1 + real DTS scheduler + Azurite)

Manual validation (only if runtime/behavior changed)

• Environment: Windows 10, Node.js 24.12.0, DTS Scheduler (West US 3), Azurite 3.35.0
• Steps + observed results:
  1. Started Azurite locally, configured DTS connection string
  2. Ran all 18 E2E tests against real DTS scheduler — all passed (239s total)
  3. Verified exported blobs in Azurite contain correct JSONL.GZ history events matching orchestration execution sequence
• Evidence: Full history event sequence verified (OrchestratorStarted → ExecutionStarted → TaskScheduled → OrchestratorStarted → TaskCompleted → ExecutionCompleted)

---

Notes for reviewers

• The E2E tests require a real DTS scheduler with entity support. They are gated behind EXPORT_HISTORY_E2E=1 and will auto-skip in CI.
• The createTimer calls in the JS orchestrator pass new Date() objects (not raw numbers) because the JS SDK interprets numeric arguments as seconds-delay and can produce invalid timestamps.
• The JS SDK does not support RetryPolicy on callActivity due to a DTS server-side Timestamp validation bug, so retry is handled at the batch level in the orchestrator.
• Version numbers were aligned to 0.1.0-beta.1 to match the branch base. The CHANGELOG removal of v0.2.0 entries should be reverted if this PR targets post-v0.2.0.

[Copilot]

Pull request overview

This PR adds a new @microsoft/durabletask-js-export-history package that enables exporting orchestration instance history to Azure Blob Storage. This is a JavaScript/TypeScript port of the Export History feature from durabletask-dotnet, providing parity with the .NET SDK.

Changes:

• New package with entity-based job management (ExportJob entity tracks lifecycle: Pending → Active → Completed/Failed)
• Export orchestrators with batch processing, retry logic (exponential backoff), and checkpoint support
• Activities for listing terminal instances and exporting history to Azure Blob Storage (JSONL.GZ or JSON formats)
• Client API (ExportHistoryClient, ExportHistoryJobClient) for creating, querying, and managing export jobs
• Comprehensive test coverage: 54 unit tests and 18 E2E tests (gated behind EXPORT_HISTORY_E2E=1)

Reviewed changes

Copilot reviewed 37 out of 39 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
packages/durabletask-js-export-history/package.json	Package configuration with dependencies, version 0.1.0-beta.1, Node.js >=22.0.0
packages/durabletask-js-export-history/tsconfig.json	TypeScript configuration extending base config
packages/durabletask-js-export-history/tsconfig.build.json	Build-specific TypeScript configuration with path mapping
packages/durabletask-js-export-history/jest.config.js	Jest configuration with module name mapping
packages/durabletask-js-export-history/src/index.ts	Main package exports for models, entity, orchestrators, activities, client, builders, constants, and errors
packages/durabletask-js-export-history/src/constants.ts	Named constants for orchestrators, activities, entities, and instance ID helpers
packages/durabletask-js-export-history/src/errors.ts	Custom error classes for validation, state transitions, and not found scenarios
packages/durabletask-js-export-history/src/models/*.ts	Type definitions for export configuration, job state, formats, filters, checkpoints, and validation logic
packages/durabletask-js-export-history/src/entity/export-job.ts	Durable entity managing job lifecycle, state transitions, and orchestrator scheduling
packages/durabletask-js-export-history/src/orchestrators/export-job-orchestrator.ts	Main orchestrator with batch processing, retry logic, checkpoint commits, and continue-as-new support
packages/durabletask-js-export-history/src/orchestrators/execute-export-job-operation-orchestrator.ts	Wrapper orchestrator for transactional entity operations
packages/durabletask-js-export-history/src/activities/list-terminal-instances-activity.ts	Activity for listing terminal orchestration instances with pagination
packages/durabletask-js-export-history/src/activities/export-instance-history-activity.ts	Activity for fetching, serializing, compressing, and uploading instance history to blob storage
packages/durabletask-js-export-history/src/client/export-history-client.ts	Client API for creating, querying, and managing export jobs via entity interactions
packages/durabletask-js-export-history/src/builders/use-export-history.ts	Helper functions to register export history components on workers and create clients
packages/durabletask-js-export-history/test/*.spec.ts	Unit tests for models, entity, errors, constants, builders, and activities
test/e2e-azuremanaged/export-history.spec.ts	E2E tests validating full export workflow against real DTS scheduler with blob verification
jest.config.js	Root Jest config updated with module name mapping for new package

---

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