@dronedeploy/rocos-js-sdk 3.1.5 → 3.1.6

package/cjs/services/CallerService.d.ts

@@ -43,6 +43,44 @@ export declare class CallerService extends BaseStreamService<ICallerStream> {
         ack$: Observable<IRocosCallerMessageResponseAck>;
         cancel: () => Promise<void>;
     };
+    /** Invoke a long-running action (ROS 2 action-server semantics) and expose its lifecycle safely.
+     *
+     * Use this instead of `call` when the request is *accepted* (ack) long before it
+     * *completes* (result) — e.g. a navigation goal or a mission. The semantics are:
+     * fire the request exactly once, hold the underlying stream open after the ack,
+     * and tear it down only when the action itself completes/errors.
+     *
+     * This differs from `call` in one crucial way: `call` builds `ack$`/`result$` on a
+     * refcounted shared source, so awaiting `ack$` (dropping the subscriber count to
+     * zero) and *then* subscribing to `result$` re-issues the goal. `callAction` pins the
+     * source with a single SDK-owned subscription for the action's lifetime, so:
+     *   - the request fires once and is never re-issued by subscriber churn,
+     *   - `ack` is a Promise (inherently replayable — await it in any order),
+     *   - `result$` replays the one-shot result, so a late or out-of-order subscriber
+     *     still receives it.
+     *
+     * Lifecycle:
+     *   - `ack`     resolves with the first acknowledgement; rejects if the action
+     *               errors (or completes) before any ack arrives.
+     *   - `result$` emits the single result and completes when the action ends. Replayed,
+     *               so subscription order relative to awaiting `ack` does not matter.
+     *   - `return$` streams live feedback/return payloads (decoded as `T`). Not replayed —
+     *               subscribe before the action emits feedback to avoid missing it.
+     *   - `cancel`  asks the server to cancel; the action then emits its result and closes.
+     *   - `close`   stops tracking the action locally *without* cancelling it on the robot,
+     *               releasing the underlying stream. For teardown paths (e.g. UI unmount)
+     *               where the action should keep running but the result is no longer needed.
+     *
+     * @see call
+     * @see callRaw
+     */
+    callAction<T = unknown>(params: ICallerCallParams): {
+        ack: Promise<IRocosCallerMessageResponseAck>;
+        result$: Observable<IRocosCallerMessageResponseResult>;
+        return$: Observable<T>;
+        cancel: () => Promise<void>;
+        close: () => void;
+    };
     protected createStream(): Promise<ICallerStream>;
     protected getStream(config: IStreamConfig): ICallerStream;
 }

package/cjs/services/CallerService.js

@@ -104,6 +104,62 @@ class CallerService extends BaseStreamService_1.BaseStreamService {
             cancel,
         };
     }
+    /** Invoke a long-running action (ROS 2 action-server semantics) and expose its lifecycle safely.
+     *
+     * Use this instead of `call` when the request is *accepted* (ack) long before it
+     * *completes* (result) — e.g. a navigation goal or a mission. The semantics are:
+     * fire the request exactly once, hold the underlying stream open after the ack,
+     * and tear it down only when the action itself completes/errors.
+     *
+     * This differs from `call` in one crucial way: `call` builds `ack$`/`result$` on a
+     * refcounted shared source, so awaiting `ack$` (dropping the subscriber count to
+     * zero) and *then* subscribing to `result$` re-issues the goal. `callAction` pins the
+     * source with a single SDK-owned subscription for the action's lifetime, so:
+     *   - the request fires once and is never re-issued by subscriber churn,
+     *   - `ack` is a Promise (inherently replayable — await it in any order),
+     *   - `result$` replays the one-shot result, so a late or out-of-order subscriber
+     *     still receives it.
+     *
+     * Lifecycle:
+     *   - `ack`     resolves with the first acknowledgement; rejects if the action
+     *               errors (or completes) before any ack arrives.
+     *   - `result$` emits the single result and completes when the action ends. Replayed,
+     *               so subscription order relative to awaiting `ack` does not matter.
+     *   - `return$` streams live feedback/return payloads (decoded as `T`). Not replayed —
+     *               subscribe before the action emits feedback to avoid missing it.
+     *   - `cancel`  asks the server to cancel; the action then emits its result and closes.
+     *   - `close`   stops tracking the action locally *without* cancelling it on the robot,
+     *               releasing the underlying stream. For teardown paths (e.g. UI unmount)
+     *               where the action should keep running but the result is no longer needed.
+     *
+     * @see call
+     * @see callRaw
+     */
+    callAction(params) {
+        const stream = this.call(params);
+        // Replay the one-shot result so subscription order never matters and a late
+        // subscriber still receives it.
+        const result = new rxjs_1.ReplaySubject(1);
+        // One SDK-owned subscription pins the shared source alive for the whole action.
+        // It fires the request once (first subscriber) and forwards the result into the
+        // replay subject, completing/erroring it when the action ends. Because this
+        // subscription outlives any `firstValueFrom(ack)` teardown, subscriber churn can
+        // never reset the source and re-issue the goal.
+        const pin = stream.result$.subscribe(result);
+        // `ack` rejects if the action errors or completes before any ack arrives. Since
+        // callAction is meant to be consumed via result$/return$ too, a caller may never
+        // touch `ack` — without a handler that rejection would surface as an unhandled
+        // promise rejection. Awaiting `action.ack` still rejects for callers who do care.
+        const ack = (0, rxjs_1.firstValueFrom)(stream.ack$);
+        ack.catch(() => { });
+        return {
+            ack,
+            result$: result.asObservable(),
+            return$: stream.return$,
+            cancel: stream.cancel,
+            close: () => pin.unsubscribe(),
+        };
+    }
     async createStream() {
         return (await this.createStreamFromConfig(identifier_1.IDENTIFIER_NAME_CALLER, {
             url: this.config.url,

package/esm/services/CallerService.d.ts

@@ -43,6 +43,44 @@ export declare class CallerService extends BaseStreamService<ICallerStream> {
         ack$: Observable<IRocosCallerMessageResponseAck>;
         cancel: () => Promise<void>;
     };
+    /** Invoke a long-running action (ROS 2 action-server semantics) and expose its lifecycle safely.
+     *
+     * Use this instead of `call` when the request is *accepted* (ack) long before it
+     * *completes* (result) — e.g. a navigation goal or a mission. The semantics are:
+     * fire the request exactly once, hold the underlying stream open after the ack,
+     * and tear it down only when the action itself completes/errors.
+     *
+     * This differs from `call` in one crucial way: `call` builds `ack$`/`result$` on a
+     * refcounted shared source, so awaiting `ack$` (dropping the subscriber count to
+     * zero) and *then* subscribing to `result$` re-issues the goal. `callAction` pins the
+     * source with a single SDK-owned subscription for the action's lifetime, so:
+     *   - the request fires once and is never re-issued by subscriber churn,
+     *   - `ack` is a Promise (inherently replayable — await it in any order),
+     *   - `result$` replays the one-shot result, so a late or out-of-order subscriber
+     *     still receives it.
+     *
+     * Lifecycle:
+     *   - `ack`     resolves with the first acknowledgement; rejects if the action
+     *               errors (or completes) before any ack arrives.
+     *   - `result$` emits the single result and completes when the action ends. Replayed,
+     *               so subscription order relative to awaiting `ack` does not matter.
+     *   - `return$` streams live feedback/return payloads (decoded as `T`). Not replayed —
+     *               subscribe before the action emits feedback to avoid missing it.
+     *   - `cancel`  asks the server to cancel; the action then emits its result and closes.
+     *   - `close`   stops tracking the action locally *without* cancelling it on the robot,
+     *               releasing the underlying stream. For teardown paths (e.g. UI unmount)
+     *               where the action should keep running but the result is no longer needed.
+     *
+     * @see call
+     * @see callRaw
+     */
+    callAction<T = unknown>(params: ICallerCallParams): {
+        ack: Promise<IRocosCallerMessageResponseAck>;
+        result$: Observable<IRocosCallerMessageResponseResult>;
+        return$: Observable<T>;
+        cancel: () => Promise<void>;
+        close: () => void;
+    };
     protected createStream(): Promise<ICallerStream>;
     protected getStream(config: IStreamConfig): ICallerStream;
 }

package/esm/services/CallerService.js

@@ -1,5 +1,5 @@
 import { ResultStatus, RocosResponseLevel, } from '../models';
-import { from, lastValueFrom, map, mergeMap, share, switchMap, take, takeUntil, throwError } from 'rxjs';
+import { ReplaySubject, firstValueFrom, from, lastValueFrom, map, mergeMap, share, switchMap, take, takeUntil, throwError, } from 'rxjs';
 import { catchError, filter } from 'rxjs/operators';
 import { getResponses, handleChunkedMessages } from '../helpers/callerMessageHelpers';
 import { BaseStreamService } from './BaseStreamService';
@@ -101,6 +101,62 @@ export class CallerService extends BaseStreamService {
             cancel,
         };
     }
+    /** Invoke a long-running action (ROS 2 action-server semantics) and expose its lifecycle safely.
+     *
+     * Use this instead of `call` when the request is *accepted* (ack) long before it
+     * *completes* (result) — e.g. a navigation goal or a mission. The semantics are:
+     * fire the request exactly once, hold the underlying stream open after the ack,
+     * and tear it down only when the action itself completes/errors.
+     *
+     * This differs from `call` in one crucial way: `call` builds `ack$`/`result$` on a
+     * refcounted shared source, so awaiting `ack$` (dropping the subscriber count to
+     * zero) and *then* subscribing to `result$` re-issues the goal. `callAction` pins the
+     * source with a single SDK-owned subscription for the action's lifetime, so:
+     *   - the request fires once and is never re-issued by subscriber churn,
+     *   - `ack` is a Promise (inherently replayable — await it in any order),
+     *   - `result$` replays the one-shot result, so a late or out-of-order subscriber
+     *     still receives it.
+     *
+     * Lifecycle:
+     *   - `ack`     resolves with the first acknowledgement; rejects if the action
+     *               errors (or completes) before any ack arrives.
+     *   - `result$` emits the single result and completes when the action ends. Replayed,
+     *               so subscription order relative to awaiting `ack` does not matter.
+     *   - `return$` streams live feedback/return payloads (decoded as `T`). Not replayed —
+     *               subscribe before the action emits feedback to avoid missing it.
+     *   - `cancel`  asks the server to cancel; the action then emits its result and closes.
+     *   - `close`   stops tracking the action locally *without* cancelling it on the robot,
+     *               releasing the underlying stream. For teardown paths (e.g. UI unmount)
+     *               where the action should keep running but the result is no longer needed.
+     *
+     * @see call
+     * @see callRaw
+     */
+    callAction(params) {
+        const stream = this.call(params);
+        // Replay the one-shot result so subscription order never matters and a late
+        // subscriber still receives it.
+        const result = new ReplaySubject(1);
+        // One SDK-owned subscription pins the shared source alive for the whole action.
+        // It fires the request once (first subscriber) and forwards the result into the
+        // replay subject, completing/erroring it when the action ends. Because this
+        // subscription outlives any `firstValueFrom(ack)` teardown, subscriber churn can
+        // never reset the source and re-issue the goal.
+        const pin = stream.result$.subscribe(result);
+        // `ack` rejects if the action errors or completes before any ack arrives. Since
+        // callAction is meant to be consumed via result$/return$ too, a caller may never
+        // touch `ack` — without a handler that rejection would surface as an unhandled
+        // promise rejection. Awaiting `action.ack` still rejects for callers who do care.
+        const ack = firstValueFrom(stream.ack$);
+        ack.catch(() => { });
+        return {
+            ack,
+            result$: result.asObservable(),
+            return$: stream.return$,
+            cancel: stream.cancel,
+            close: () => pin.unsubscribe(),
+        };
+    }
     async createStream() {
         return (await this.createStreamFromConfig(IDENTIFIER_NAME_CALLER, {
             url: this.config.url,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dronedeploy/rocos-js-sdk",
-  "version": "3.1.5",
+  "version": "3.1.6",
   "description": "Javascript SDK for rocos",
   "main": "cjs/index.js",
   "module": "esm/index.js",