Add spinUntilFutureComplete for Promise-based spin lifecycle

[minggangw]

Adds spinUntilFutureComplete(), the rclnodejs equivalent of rclpy's spin_until_future_complete(node, future, timeout_sec). This method starts spinning the node (if not already spinning), awaits a Promise to settle, and automatically stops spinning when done (if it started it). Supports an optional timeout that rejects with TimeoutError on expiry. Validates timeoutMs with TypeValidationError / RangeValidationError for type safety. Guarantees cleanup in all code paths via try/finally, eliminating a common source of resource leaks where users forget to call node.stop() after async operations.

New files:

• test/test-spin-until-future-complete.js — 8 tests covering: promise resolution, rejection, timeout (asserts TimeoutError by name), already-spinning preservation, auto-stop on completion, delayed promises, invalid argument validation, and module-level function.

Modified files:

• lib/node.js — Added spinUntilFutureComplete(promise, timeoutMs) async method. Validates the promise argument via TypeValidationError. Validates timeoutMs when provided: TypeValidationError for non-finite numbers, RangeValidationError for negative values. Manages spin start/stop lifecycle via try/finally, and uses Promise.race with a TimeoutError-rejecting timeout promise when timeoutMs is provided. Added TimeoutError to the destructured imports from errors.js.
• index.js — Added module-level spinUntilFutureComplete(node, promise, timeoutMs) wrapper matching the rclpy global function pattern.
• types/node.d.ts — Added generic TypeScript declaration spinUntilFutureComplete<T>(promise: Promise<T>, timeoutMs?: number): Promise<T>.
• types/index.d.ts — Added module-level TypeScript declaration spinUntilFutureComplete<T>(node: Node, promise: Promise<T>, timeoutMs?: number): Promise<T>.

Fix: #1441

[Copilot]

Pull request overview

Adds a Promise-oriented spinning helper to rclnodejs, mirroring rclpy’s spin_until_future_complete to simplify async workflows and reduce missed node.stop() cleanup.

Changes:

• Added Node.spinUntilFutureComplete(promise, timeoutMs?) to manage spin start/stop around an awaited Promise.
• Added module-level rclnodejs.spinUntilFutureComplete(node, promise, timeoutMs?) wrapper.
• Added TypeScript typings and a new mocha test suite covering resolution/rejection/timeout and spin state preservation.

Reviewed changes

Copilot reviewed 3 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
lib/node.js	Implements spinUntilFutureComplete() including spin lifecycle management and optional timeout.
index.js	Exposes a module-level wrapper function delegating to the Node method.
types/node.d.ts	Adds the Node method TypeScript declaration and docs.
types/index.d.ts	Adds the module-level TypeScript declaration and docs.
test/test-spin-until-future-complete.js	Adds test coverage for success, failure, timeout, and wrapper usage.

---

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

[coveralls]

coverage: 85.99% (+0.05%) from 85.941%
when pulling 9fc7f4c on minggangw:fix-1441
into e71e427 on RobotWebTools:develop.