feat: expose purge completion status

[wangbill (YunchuWang)]

Summary

What changed?

• Expose optional PurgeResult.isComplete and forward res.getIscomplete()?.getValue() for both single-instance and filtered purges.
• Preserve all three states: true means complete, false means partial, and an absent protobuf wrapper becomes undefined (unknown).
• Keep deletedInstanceCount and new PurgeResult(count) compatible. Add JSDoc, release notes, and focused regression coverage.

Why is this change needed?

A backend can delete some instances and return isComplete: false. The deletion count alone cannot tell callers whether the purge finished, including when the count is zero. The completion flag already exists in the checked-in protobuf bindings; this change stops dropping it.

This aligns with the .NET SDK's nullable completion contract and gRPC response mapping, using JavaScript undefined for unknown.

Issues / work items

• Resolves: N/A; no linked issue.
• Related: Purge completion-status parity only.

---

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?
  • If yes:
    • Impact: N/A; the constructor's new argument and public property are optional.
    • Migration guidance: None required. Treat an absent completion status as unknown, not complete or partial.

---

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 coding agent.
• AI-assisted areas/files: Core purge result, client response mapping, purge regression tests, and changelog.
• What you changed after AI output: No human edits are claimed. The agent implemented and ran the checks below; human review remains pending.

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

• Result: Passed locally on Windows, Node.js v24.14.0, npm 11.9.0.
• TDD RED: npm test -w @microsoft/durabletask-js -- --runTestsByPath test/client-purge.spec.ts failed with the expected 8 missing-completion assertions, with 15 existing-behavior cases passing. Both true and false failed for both purge paths at counts 0 and 3.
• GREEN: npm test -w @microsoft/durabletask-js -- --runTestsByPath test/client-purge.spec.ts test/in-memory-backend.spec.ts test/in-memory-backend-entities.spec.ts passed 98 tests across 3 suites, including all 23 purge regression tests.
• Consumer coverage: npm test -w durable-functions -- --runTestsByPath test/unit/client-query.spec.ts test/unit/client.spec.ts passed 37 tests across 2 suites.
• Build/types: npm run build -w durable-functions passed, including the core build and generated declaration files.
• Scoped lint passed: npx --no-install eslint packages\durabletask-js\src\client\client.ts packages\durabletask-js\src\orchestration\orchestration-purge-result.ts packages\durabletask-js\test\client-purge.spec.ts.
• Formatting passed: npx --no-install prettier --check --end-of-line auto CHANGELOG.md packages\durabletask-js\src\client\client.ts packages\durabletask-js\src\orchestration\orchestration-purge-result.ts packages\durabletask-js\test\client-purge.spec.ts. Existing client/changelog formatting also matched the remote-main baseline.
• git diff --check passed. Normal Husky/lint-staged ESLint hooks passed during commit.

The new tests use the real generated protobuf response and a binary serialization/deserialization round trip, with only the unary RPC mocked. They cover explicit false versus absent wrappers, legacy construction, unchanged counts, request fields/recursive options, missing responses, service errors, and the existing local-only filter timeout without cancellation or retries.

Manual validation (only if runtime/behavior changed)

• Environment (OS, Node.js version, components): Windows, Node.js v24.14.0; local automated checks only.
• Steps + observed results: No live Azure, DTS emulator, sidecar, or Functions host validation was performed. No resources were provisioned.
• Evidence (optional): Hosted CI is pending; broad repository suites and service-dependent E2E checks were not run locally. Existing npm always-auth configuration and dependency deprecation warnings were observed during the normal dependency restore; no registry/auth settings or dependencies were changed.

---

Notes for reviewers

• No protobuf regeneration, backend changes, new dependencies, auto-purge loop, server-timeout wiring, or cancellation changes.
• The in-memory test client continues returning its existing count-only result; no completion status is invented. The separate classic Functions PurgeHistoryResult and HTTP responses are unchanged.
• This branch is independent of other parity work and is based on main at 72b79a5a3012d630d2bdf5c2b0f75ef37ef63b39.

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

Review effort: Lite
Findings: None

What changed in this PR

Expose purge completion semantics to SDK callers by preserving the backend’s optional isComplete flag (true/false/undefined) in PurgeResult, with regression tests and release notes.

Changes:

• Extend PurgeResult with optional isComplete?: boolean while keeping count-only construction compatible.
• Map PurgeInstancesResponse.isComplete (protobuf wrapper) into PurgeResult in the gRPC client.
• Add focused purge regression tests and document the feature in CHANGELOG.md.

File	Description
packages/​durabletask-js/​src/​orchestration/​orchestration-purge-result.ts	Adds optional isComplete to the public result type and constructor.
packages/​durabletask-js/​src/​client/​client.ts	Forwards protobuf isComplete wrapper value into PurgeResult.
packages/​durabletask-js/​test/​client-purge.spec.ts	Adds regression tests covering true/false/undefined completion and existing purge behaviors.
CHANGELOG.md	Documents the newly exposed PurgeResult.isComplete semantics.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.