@dronedeploy/rocos-js-sdk 4.4.3 → 4.4.5

package/cjs/models/gamepad/GamepadConfig.d.ts

@@ -31,6 +31,18 @@ export declare enum GamepadButtonType {
 }
 /** Per-axis tuning keyed by GamepadButtonType. Absent entirely on configs saved before axis tuning existed. */
 export type GamepadAxisValueMap = Partial<Record<GamepadButtonType, number>>;
+/** Same shape as GamepadAxisValueMap, keyed by any input — a modifier is usually a bumper or trigger, not an axis. */
+export type GamepadInputValueMap = Partial<Record<GamepadButtonType, number>>;
+/**
+ * Engage point for an input with no GamepadConfig.modifierThresholds entry. Exported so editor and
+ * interpreter agree: a modifier held at 0.5 in one and 0.75 in the other works on screen, not on the robot.
+ */
+export declare const DEFAULT_MODIFIER_THRESHOLD = 0.5;
+/**
+ * Release point as a fraction of the engage threshold. Releasing at the engage value flaps the layer at
+ * frame rate while a trigger rests on the threshold. Exported for the same reason as the threshold.
+ */
+export declare const MODIFIER_RELEASE_FRACTION = 0.7;
 export declare enum GamepadTriggerType {
     ONCE = "once",
     CONTINUOUSLY = "continuously"
@@ -54,6 +66,15 @@ export interface GamepadAction {
     triggerType: GamepadTriggerType;
     /** Milliseconds between repeats. Only meaningful for `continuously`. */
     frequency: number;
+    /**
+     * Inputs that must be held for this action to fire. A set: unordered, and absent or empty is the base
+     * layer, eligible whatever is held — which is what leaves pre-modifier configs unaffected.
+     *
+     * Matched on `type` alone, since `text` is a display label and the same input reaches us as "LB" from
+     * one author and "L1" from another. Must not contain the action's own `source`, which the triggering
+     * press would satisfy on its own.
+     */
+    modifiers?: GamepadButtonRef[];
 }
 export interface GamepadVariable {
     name: string;
@@ -80,6 +101,11 @@ export interface GamepadConfig {
     variables: GamepadVariable[];
     axisDeadzones?: GamepadAxisValueMap;
     axisExpos?: GamepadAxisValueMap;
+    /**
+     * Engage point per modifier input. Profile-level rather than per-action so one trigger cannot engage at
+     * two values. Absent entries use DEFAULT_MODIFIER_THRESHOLD.
+     */
+    modifierThresholds?: GamepadInputValueMap;
 }
 /** One stored gamepad config, scoped to a specific physical controller model (GamepadConfig.gamepad). */
 export type GamepadConfigItem = ConfigGroupItem<GamepadConfig>;

package/cjs/models/gamepad/GamepadConfig.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GamepadCommandVersion = exports.GamepadTriggerType = exports.GamepadButtonType = void 0;
+exports.GamepadCommandVersion = exports.GamepadTriggerType = exports.MODIFIER_RELEASE_FRACTION = exports.DEFAULT_MODIFIER_THRESHOLD = exports.GamepadButtonType = void 0;
 // Ref: https://github.com/alaingilbert/GamepadJs
 var GamepadButtonType;
 (function (GamepadButtonType) {
@@ -33,6 +33,16 @@ var GamepadButtonType;
     GamepadButtonType[GamepadButtonType["SQUARE"] = 26] = "SQUARE";
     GamepadButtonType[GamepadButtonType["TRIANGLE"] = 27] = "TRIANGLE";
 })(GamepadButtonType || (exports.GamepadButtonType = GamepadButtonType = {}));
+/**
+ * Engage point for an input with no GamepadConfig.modifierThresholds entry. Exported so editor and
+ * interpreter agree: a modifier held at 0.5 in one and 0.75 in the other works on screen, not on the robot.
+ */
+exports.DEFAULT_MODIFIER_THRESHOLD = 0.5;
+/**
+ * Release point as a fraction of the engage threshold. Releasing at the engage value flaps the layer at
+ * frame rate while a trigger rests on the threshold. Exported for the same reason as the threshold.
+ */
+exports.MODIFIER_RELEASE_FRACTION = 0.7;
 var GamepadTriggerType;
 (function (GamepadTriggerType) {
     GamepadTriggerType["ONCE"] = "once";

package/cjs/services/AssetStorageService.js

@@ -99,7 +99,12 @@ class AssetStorageService extends BaseServiceAbstract_1.BaseServiceAbstract {
      * @param signedURL
      */
     async listFlowAssets(projectId, flowId, flowInstance, parent = '/', signedURL = false) {
-        return this.callGet((0, formatServiceUrl_1.formatServiceUrl)(api_1.API_PROJECT_FLOW_ASSET_PATH_URL, { url: this.config.url, projectId, flowId, flowInstance }, this.config.insecure), `Failed to get asset for ${projectId}, flow ${flowId}, flow instance ${flowInstance}.`, { parent, signedURL });
+        return this.callGet((0, formatServiceUrl_1.formatServiceUrl)(api_1.API_PROJECT_FLOW_ASSET_PATH_URL, {
+            url: this.config.url,
+            projectId,
+            flowId: encodeURIComponent(flowId),
+            flowInstance: encodeURIComponent(flowInstance),
+        }, this.config.insecure), `Failed to get asset for ${projectId}, flow ${flowId}, flow instance ${flowInstance}.`, { parent, signedURL });
     }
     /**
      * List assets for a mission

package/cjs/services/BaseServiceAbstract.js

@@ -44,7 +44,7 @@ class BaseServiceAbstract {
                 requestConfig.body = JSON.stringify(payload);
                 requestConfig.headers = { ...requestConfig.headers, 'Content-Type': 'application/json' };
             }
-            return this.fetchOrThrow(formattedUrl, requestConfig, config?.responseType);
+            return await this.fetchOrThrow(formattedUrl, requestConfig, config?.responseType);
         }
         catch (e) {
             const message = errorMessage;

package/cjs/services/BaseStreamService.d.ts

@@ -1,3 +1,4 @@
+import { IAcquiredStream } from '../api/StreamRegister';
 import { IBaseService, IBaseStream, IRocosSDKConfig, IStreamConfig, SubscriberStatusEnum } from '../models';
 import { ISubscriberStatus } from '../models/ISubscriberStatus';
 import { Logger } from 'loglevel';
@@ -10,7 +11,17 @@ export declare abstract class BaseStreamService<T extends IBaseStream, C extends
     protected constructor(name: string, config: IRocosSDKConfig);
     getStatus(): boolean;
     protected initStream(stream: T): Promise<void>;
-    protected createStreamFromConfig(identifier: string, config: C, onAcquire?: (stream: T) => void): Promise<{
+    /**
+     * Get-or-create the shared stream for this identifier/scope and take a refcount on it,
+     * synchronously. Holders that stop consuming must call the handle's release(); the registry
+     * tears the stream down when the last holder releases.
+     */
+    protected acquireStream(identifier: string, config: C): IAcquiredStream<T>;
+    /**
+     * Acquire-and-init without a paired release: callers of this path hold their refcount for the
+     * life of the process, so these streams are only torn down by removeAllStreams.
+     */
+    protected createStreamFromConfig(identifier: string, config: C): Promise<{
         stream: T;
         isNew: boolean;
     }>;

package/cjs/services/BaseStreamService.js

@@ -1,10 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseStreamService = void 0;
+const StreamRegister_1 = require("../api/StreamRegister");
 const models_1 = require("../models");
 const RocosLogger_1 = require("../logger/RocosLogger");
 const RocosStore_1 = require("../store/RocosStore");
-const StreamRegister_1 = require("../api/StreamRegister");
 const rxjs_1 = require("rxjs");
 class BaseStreamService {
     constructor(name, config) {
@@ -32,40 +32,29 @@ class BaseStreamService {
         }
         authService.startTokenRefreshChecker();
     }
-    async createStreamFromConfig(identifier, config, onAcquire) {
+    /**
+     * Get-or-create the shared stream for this identifier/scope and take a refcount on it,
+     * synchronously. Holders that stop consuming must call the handle's release(); the registry
+     * tears the stream down when the last holder releases.
+     */
+    acquireStream(identifier, config) {
         const identifierWithScope = StreamRegister_1.StreamRegister.getIdentifier(identifier, config.scope);
-        const streamRegister = StreamRegister_1.StreamRegister.getInstance();
-        let stream = streamRegister.getStream(identifierWithScope);
-        let isNew = false;
-        if (!stream) {
-            isNew = true;
-            stream = this.getStream(config);
+        return StreamRegister_1.StreamRegister.getInstance().acquireStream(identifierWithScope, () => {
+            const stream = this.getStream(config);
             stream.statusStream$.subscribe((msg) => {
                 this.status = msg === models_1.SubscriberStatusEnum.STOPPED || msg === models_1.SubscriberStatusEnum.ALIVE;
                 this.status$.next(msg);
             });
-            streamRegister.addStream(stream);
-        }
-        // Acquire synchronously with the lookup/registration above, before any await. A stream is
-        // stopped and deregistered the instant its refcount hits zero, so a deferred acquire can land on
-        // a dead instance — including a freshly-registered stream torn down during the init await below.
-        onAcquire?.(stream);
-        if (isNew) {
-            try {
-                await this.initStream(stream);
-            }
-            catch (e) {
-                // Evict eagerly, before the error reaches the subscriber, so a synchronous resubscribe
-                // can't re-acquire this uninitialised instance.
-                streamRegister.removeStream(stream);
-                throw e;
-            }
-            // If a concurrent teardown deregistered this stream during init, init() has opened a receiver
-            // on an instance nothing can reach; close it.
-            if (streamRegister.getStream(identifierWithScope) !== stream) {
-                stream.stopStream();
-            }
-        }
+            return stream;
+        }, (stream) => this.initStream(stream));
+    }
+    /**
+     * Acquire-and-init without a paired release: callers of this path hold their refcount for the
+     * life of the process, so these streams are only torn down by removeAllStreams.
+     */
+    async createStreamFromConfig(identifier, config) {
+        const { stream, isNew, ready } = this.acquireStream(identifier, config);
+        await ready;
         return { stream, isNew };
     }
 }

package/cjs/services/EnvironmentService.d.ts

@@ -21,6 +21,10 @@ export declare class EnvironmentService extends BaseServiceAbstract implements I
      * CAUTION: This will delete the existing environment and create
      * a new one. Think of this as a "reset" for the environment.
      * This will cause ALL edges to other objects (assets, panos, etc) to be removed.
+     *
+     * @deprecated Prefer {@link update}. The environment has no create endpoint -
+     * `PUT /environments` is the only full-replace write, so this method now
+     * issues the same request as `update`.
      */
     set(projectId: string, scene: unknown): Promise<void>;
     /**

package/cjs/services/EnvironmentService.js

@@ -36,9 +36,13 @@ class EnvironmentService extends BaseServiceAbstract_1.BaseServiceAbstract {
      * CAUTION: This will delete the existing environment and create
      * a new one. Think of this as a "reset" for the environment.
      * This will cause ALL edges to other objects (assets, panos, etc) to be removed.
+     *
+     * @deprecated Prefer {@link update}. The environment has no create endpoint -
+     * `PUT /environments` is the only full-replace write, so this method now
+     * issues the same request as `update`.
      */
     async set(projectId, scene) {
-        return this.callPost((0, formatServiceUrl_1.formatServiceUrl)(api_1.API_PROJECT_ENVIRONMENT_URL, { url: this.config.url, projectId }, this.config.insecure), scene, `Failed to set environment for ${projectId}.`);
+        return this.callPut((0, formatServiceUrl_1.formatServiceUrl)(api_1.API_PROJECT_ENVIRONMENT_URL, { url: this.config.url, projectId }, this.config.insecure), scene, `Failed to set environment for ${projectId}.`);
     }
     /**
      * Update Environment

package/cjs/services/MapService.d.ts

@@ -36,10 +36,22 @@ export declare class MapService extends BaseServiceAbstract implements IBaseServ
      */
     listDeployedMaps(projectId: string, callsign: string): Promise<Map[]>;
     /**
-     * Creates a new map by merging two existing maps
+     * Creates a new map by folding two existing maps together.
+     *
+     * `options.name` is the mapId of the new target map and must not already
+     * exist. `options.callsign` is accepted for signature compatibility and is
+     * not sent: the union target is a cloud map, and deploying it to a robot is
+     * {@link deploy}'s job.
+     *
+     * `options.description` needs a second request - the union endpoint takes no
+     * metadata. That request is best-effort: a failure is logged and swallowed,
+     * because the map itself already exists by then and retrying `merge` would
+     * conflict on `targetMapId`. Call {@link updateMetadata} directly to retry
+     * the description.
+     *
      * @param projectId Project ID
-     * @param maps Array of two map IDs to merge
-     * @param options Options to create the new map
+     * @param maps Array of two source map IDs to fold together
+     * @param options `name` for the new map, optional `description`
      */
     merge(projectId: string, maps: [string, string], options: {
         name: string;

package/cjs/services/MapService.js

@@ -55,26 +55,38 @@ class MapService extends BaseServiceAbstract_1.BaseServiceAbstract {
         return resp.maps;
     }
     /**
-     * Creates a new map by merging two existing maps
+     * Creates a new map by folding two existing maps together.
+     *
+     * `options.name` is the mapId of the new target map and must not already
+     * exist. `options.callsign` is accepted for signature compatibility and is
+     * not sent: the union target is a cloud map, and deploying it to a robot is
+     * {@link deploy}'s job.
+     *
+     * `options.description` needs a second request - the union endpoint takes no
+     * metadata. That request is best-effort: a failure is logged and swallowed,
+     * because the map itself already exists by then and retrying `merge` would
+     * conflict on `targetMapId`. Call {@link updateMetadata} directly to retry
+     * the description.
+     *
      * @param projectId Project ID
-     * @param maps Array of two map IDs to merge
-     * @param options Options to create the new map
+     * @param maps Array of two source map IDs to fold together
+     * @param options `name` for the new map, optional `description`
      */
     async merge(projectId, maps, options) {
         if (maps.length !== 2)
             throw new Error('You must provide two maps to merge.');
-        const payload = {
-            projectID: projectId,
-            mapIDLeft: maps[0],
-            mapIDRight: maps[1],
-            name: options.name,
-            description: options.description,
-            callsign: options.callsign,
-        };
-        return this.callPost((0, formatServiceUrl_1.formatServiceUrl)(api_1.API_GRAPHS_MAPS_MERGE_URL, {
+        await this.callPost((0, formatServiceUrl_1.formatServiceUrl)(api_1.API_GRAPHS_MAPS_UNION_URL, {
             url: this.config.url,
             projectId,
-        }, this.config.insecure), payload, 'Failed to merge maps.');
+        }, this.config.insecure), { targetMapId: options.name, sources: [maps[0], maps[1]] }, 'Failed to merge maps.');
+        if (options.description) {
+            try {
+                await this.updateMetadata(projectId, options.name, { description: options.description });
+            }
+            catch (e) {
+                this.logger.error(`Map ${options.name} was created but its description could not be set.`, e);
+            }
+        }
     }
     /** Returns a map in its canonical form
      *

package/cjs/services/SearchService.js

@@ -39,7 +39,7 @@ class SearchService extends BaseStreamService_1.BaseStreamService {
         return stream.deleteProjectData(params);
     }
     async createStream() {
-        const newStream = await this.createStreamFromConfig(identifier_1.IDENTIFIER_NAME_FILE_ACCESSOR, {
+        const newStream = await this.createStreamFromConfig(identifier_1.IDENTIFIER_NAME_SEARCH, {
             url: this.config.url,
             token: this.config.token,
             scope: 'default',

package/cjs/services/TargetService.js

@@ -56,10 +56,10 @@ class TargetService extends BaseServiceAbstract_1.BaseServiceAbstract {
         });
     }
     async addMedia(projectId, targetId, media) {
-        await this.callPost((0, formatServiceUrl_1.formatServiceUrl)(api_1.API_GRAPHS_TARGETS_URL, {
+        await this.callPut((0, formatServiceUrl_1.formatServiceUrl)(api_1.API_GRAPHS_TARGET_MEDIA_URL, {
             url: this.config.url,
             projectId,
-            targetId,
+            targetId: encodeURIComponent(targetId),
         }, this.config.insecure), media, 'Failed to add media to a target');
     }
 }

package/cjs/services/TelemetryService.d.ts

@@ -46,6 +46,6 @@ export declare class TelemetryService extends BaseStreamService<ITelemetryStream
     monitorTelemetryWithTimeout(projectId: string, callsign: string, source: string, heartbeatTimeoutMs?: number, intervalMs?: number): Observable<TelemetryMonitorStatus>;
     protected initStream(stream: ITelemetryStream): Promise<void>;
     private buildScope;
-    private createStream;
+    private buildStreamConfig;
     protected getStream(config: ITelemetryStreamConfig): ITelemetryStream;
 }

package/cjs/services/TelemetryService.js

@@ -55,20 +55,33 @@ class TelemetryService extends BaseStreamService_1.BaseStreamService {
         // scope is used as a key to generate unique streams
         // ideally there should be just one concurrent stream opened
         const scope = this.buildScope(params, callsignsLookup);
-        const callsigns = callsignsLookup.lookupValue;
         const subscriptionParams = {
             uniqueId: (0, getUniqueId_1.getUniqueId)(params.projectId, callsignsLookup, sources, scope),
-            callsigns: callsignsLookup?.lookupType === models_1.CallsignsLookupType.List ? callsignsLookup.lookupValue : [],
+            callsigns: callsignsLookup.getCallsigns(),
             sources,
         };
         // `defer` acquires the stream only when subscribed; `finalize` releases it on unsubscribe, error
-        // and complete — so acquire and release stay balanced on every path.
+        // and complete — so acquire and release stay balanced on every path. The registry refcount taken
+        // here keeps the stream alive until the finalize, so everything in between is race-free.
         return (0, rxjs_1.defer)(() => {
-            let acquired;
-            const stream$ = this.createStream(params.projectId, callsignsLookup, sources, scope, (stream) => {
-                acquired = stream;
+            const { stream, isNew, ready, release } = this.acquireStream(identifier_1.IDENTIFIER_NAME_TELEMETRY, this.buildStreamConfig(params.projectId, callsignsLookup, sources, scope));
+            try {
                 stream.addSubscription(subscriptionParams);
-            }).then((stream) => {
+                if (!isNew) {
+                    stream.statusStream$.subscribe((msg) => {
+                        this.streamStatusSubject$.next({
+                            scope,
+                            status: msg,
+                        });
+                    });
+                }
+            }
+            catch (e) {
+                // finalize below is not wired up yet, so a throw here must hand the refcount back itself.
+                release();
+                throw e;
+            }
+            const messages$ = ready.then(() => {
                 if (!this.statusSubscription) {
                     this.statusSubscription = stream.statusStream$.subscribe((msg) => {
                         this.status = msg === models_1.SubscriberStatusEnum.STOPPED || msg === models_1.SubscriberStatusEnum.ALIVE;
@@ -77,9 +90,12 @@ class TelemetryService extends BaseStreamService_1.BaseStreamService {
                 }
                 return (0, rxjs_1.from)(stream.messageStream$);
             });
-            return (0, rxjs_1.from)(stream$).pipe((0, rxjs_1.mergeAll)(), (0, operators_1.filter)((message) => {
-                return callsigns.includes(message.callsign) && sources.includes(message.source);
-            }), (0, operators_1.finalize)(() => acquired?.removeSubscription(subscriptionParams, params.terminateReceiverGroupOnUnsubscribe)));
+            return (0, rxjs_1.from)(messages$).pipe((0, rxjs_1.mergeAll)(), (0, operators_1.filter)((message) => {
+                return callsignsLookup.includesCallsign(message.callsign) && sources.includes(message.source);
+            }), (0, operators_1.finalize)(() => {
+                void stream.removeSubscription(subscriptionParams, params.terminateReceiverGroupOnUnsubscribe);
+                release();
+            }));
         });
     }
     /**
@@ -159,8 +175,8 @@ class TelemetryService extends BaseStreamService_1.BaseStreamService {
             return `${params.projectId}-default-${(0, flattenCallsignsLookup_1.flattenCallsignsLookup)(callsignsLookup).join()}`;
         return `${params.projectId}-default`;
     }
-    async createStream(projectId, callsignsLookup, sources, scope, onAcquire) {
-        const newStream = await this.createStreamFromConfig(identifier_1.IDENTIFIER_NAME_TELEMETRY, {
+    buildStreamConfig(projectId, callsignsLookup, sources, scope) {
+        return {
             url: this.config.url,
             projectId,
             callsignsLookup,
@@ -172,16 +188,7 @@ class TelemetryService extends BaseStreamService_1.BaseStreamService {
             insecure: this.config.insecure,
             transport: this.config.transport,
             fetch: this.config.fetch,
-        }, onAcquire);
-        if (!newStream.isNew) {
-            newStream.stream.statusStream$.subscribe((msg) => {
-                this.streamStatusSubject$.next({
-                    scope,
-                    status: msg,
-                });
-            });
-        }
-        return newStream.stream;
+        };
     }
     getStream(config) {
         if (config.transport === 'grpc-web') {

package/cjs/services/WebRTCSignallingService.js

@@ -37,11 +37,9 @@ class WebRTCSignallingService {
     }
     async createSignallingStream() {
         const scope = 'default';
-        const identifier = StreamRegister_1.StreamRegister.getIdentifier(identifier_1.IDENTIFIER_NAME_COMMAND, scope);
-        const streamRegister = StreamRegister_1.StreamRegister.getInstance();
-        let stream = streamRegister.getStream(identifier);
-        if (!stream) {
-            stream = this.getStream({
+        const identifier = StreamRegister_1.StreamRegister.getIdentifier(identifier_1.IDENTIFIER_NAME_WEBRTC_SIGNALLING, scope);
+        const { stream, ready } = StreamRegister_1.StreamRegister.getInstance().acquireStream(identifier, () => {
+            const newStream = this.getStream({
                 url: this.config.url,
                 token: this.config.token,
                 scope,
@@ -49,13 +47,13 @@ class WebRTCSignallingService {
                 port: this.config.port,
                 insecure: this.config.insecure,
             });
-            stream.statusStream$.subscribe((msg) => {
+            newStream.statusStream$.subscribe((msg) => {
                 this.status = msg === SubscriberStatusEnum_1.SubscriberStatusEnum.STOPPED || msg === SubscriberStatusEnum_1.SubscriberStatusEnum.ALIVE;
                 this.status$.next(msg);
             });
-            streamRegister.addStream(stream);
-            await this.initStream(stream);
-        }
+            return newStream;
+        }, (newStream) => this.initStream(newStream));
+        await ready;
         return stream;
     }
     async initStream(stream) {

package/esm/api/StreamRegister.d.ts

@@ -1,13 +1,28 @@
 import { IBaseStream } from '../models';
+export interface IAcquiredStream<T extends IBaseStream> {
+    stream: T;
+    isNew: boolean;
+    /** Settles when the stream's one-time init completes; rejects (and evicts) if init fails. */
+    ready: Promise<void>;
+    /** Releases this holder's refcount. One-shot: extra calls are ignored. */
+    release: () => void;
+}
+/**
+ * Sole owner of stream lifecycle. Streams are shared per identifier and refcounted: acquireStream
+ * gets-or-creates and increments in one synchronous step, and the returned handle's release()
+ * tears the stream down when the last holder leaves. Teardown never happens outside
+ * release/removeAllStreams, so a held stream can not be stopped or replaced underneath its holders.
+ */
 export declare class StreamRegister {
-    private teleStreams;
+    private entries;
     private logger;
     private static instance;
     private constructor();
     static getInstance(): StreamRegister;
     static getIdentifier($identifier: string, scope?: string): string;
-    addStream(stream: IBaseStream): void;
+    acquireStream<T extends IBaseStream>(identifier: string, create: () => T, init: (stream: T) => Promise<void>): IAcquiredStream<T>;
     getStream(identifier: string): IBaseStream | undefined;
-    removeStream(stream: IBaseStream): void;
     removeAllStreams(): boolean;
+    private release;
+    private evict;
 }

package/esm/api/StreamRegister.js

@@ -1,8 +1,14 @@
 import { RocosError, errorCodes } from '../models';
 import { RocosLogger } from '../logger/RocosLogger';
+/**
+ * Sole owner of stream lifecycle. Streams are shared per identifier and refcounted: acquireStream
+ * gets-or-creates and increments in one synchronous step, and the returned handle's release()
+ * tears the stream down when the last holder leaves. Teardown never happens outside
+ * release/removeAllStreams, so a held stream can not be stopped or replaced underneath its holders.
+ */
 export class StreamRegister {
     constructor() {
-        this.teleStreams = new Map();
+        this.entries = new Map();
         this.logger = RocosLogger.getInstance('StreamRegister');
     }
     static getInstance() {
@@ -14,55 +20,83 @@ export class StreamRegister {
     static getIdentifier($identifier, scope) {
         return `${$identifier}-${scope ?? ''}`;
     }
-    addStream(stream) {
-        try {
-            // Stop any existing occupant of this key before overwriting it.
-            const existing = this.teleStreams.get(stream.identifier);
-            if (existing && existing !== stream) {
-                existing.stopStream();
-            }
-            this.teleStreams.set(stream.identifier, stream);
+    acquireStream(identifier, create, init) {
+        let entry = this.entries.get(identifier);
+        let isNew = false;
+        if (entry) {
+            entry.refCount++;
         }
-        catch (e) {
-            this.logger.error(`Failed to add stream to list. identifier: ${stream.identifier}`, e);
-            if (e instanceof Error || typeof e === 'string') {
-                throw new RocosError(e, errorCodes.STREAM_LISTENER_ERROR);
-            }
-            else {
-                throw e;
-            }
+        else {
+            isNew = true;
+            const stream = create();
+            const ready = init(stream).catch((error) => {
+                this.logger.error(`Stream init failed, evicting. identifier: ${identifier}`, error);
+                try {
+                    this.evict(identifier, stream);
+                }
+                catch (evictionError) {
+                    this.logger.error(`Failed to evict after init failure. identifier: ${identifier}`, evictionError);
+                }
+                throw error;
+            });
+            // `ready` is stored and shared; this discarded catch pins a rejection observer so an init
+            // failure can never surface as an unhandled rejection, while holders still see the rejection.
+            void ready.catch(() => undefined);
+            entry = { stream, refCount: 1, ready };
+            this.entries.set(identifier, entry);
         }
+        const held = entry;
+        let released = false;
+        const release = () => {
+            // One-shot so a double release can never consume another holder's refcount.
+            if (released)
+                return;
+            released = true;
+            this.release(identifier, held);
+        };
+        return { stream: entry.stream, isNew, ready: entry.ready, release };
     }
     getStream(identifier) {
-        return this.teleStreams.get(identifier);
+        return this.entries.get(identifier)?.stream;
     }
-    removeStream(stream) {
-        try {
-            stream.stopStream();
-            // Only clear the entry if this instance still owns the key: a replacement may already hold it,
-            // and evicting that would leave subscribers forking duplicate streams for the scope.
-            if (this.teleStreams.get(stream.identifier) === stream) {
-                this.teleStreams.delete(stream.identifier);
-            }
-        }
-        catch (e) {
-            this.logger.error(`Failed to remove stream from list. identifier: ${stream.identifier}`, e);
-            if (e instanceof Error || typeof e === 'string') {
-                throw new RocosError(e, errorCodes.STREAM_LISTENER_ERROR);
+    removeAllStreams() {
+        for (const [, entry] of this.entries.entries()) {
+            try {
+                entry.stream.stopStream();
             }
-            else {
-                throw e;
+            catch (e) {
+                this.logger.error(`error removing stream, ${e}`);
             }
         }
+        this.entries.clear();
+        return true;
     }
-    removeAllStreams() {
+    release(identifier, entry) {
+        if (this.entries.get(identifier) !== entry)
+            return; // already evicted, or force-removed
+        entry.refCount--;
+        if (entry.refCount > 0)
+            return;
+        // Wait for init to settle before tearing down, so init can never open resources on an already
+        // stopped stream. A re-acquire in the meantime revives the entry and cancels the teardown.
+        void entry.ready
+            .catch(() => undefined)
+            .then(() => {
+            if (this.entries.get(identifier) === entry && entry.refCount <= 0) {
+                this.evict(identifier, entry.stream);
+            }
+        })
+            .catch((e) => this.logger.error(`Failed to evict stream. identifier: ${identifier}`, e));
+    }
+    evict(identifier, stream) {
         try {
-            for (const [, stream] of this.teleStreams.entries()) {
-                this.removeStream(stream);
+            if (this.entries.get(identifier)?.stream === stream) {
+                this.entries.delete(identifier);
             }
+            stream.stopStream();
         }
         catch (e) {
-            this.logger.error(`error removing stream, ${e}`);
+            this.logger.error(`Failed to remove stream from list. identifier: ${identifier}`, e);
             if (e instanceof Error || typeof e === 'string') {
                 throw new RocosError(e, errorCodes.STREAM_LISTENER_ERROR);
             }
@@ -70,6 +104,5 @@ export class StreamRegister {
                 throw e;
             }
         }
-        return true;
     }
 }

package/esm/api/atoms/StreamHeartbeat.js

@@ -35,7 +35,7 @@ export class StreamHeartbeat {
             this.callback = callback;
             this.timeout = timeout;
             this.logger.info('Creating stream heartbeat');
-            this.interval = setInterval(this.callback, this.timeout);
+            this.interval = setInterval(() => this.callback?.(), this.timeout);
         }
         else {
             this.logger.warn('Stream heartbeat already exists');
@@ -55,7 +55,7 @@ export class StreamHeartbeat {
         // if the health check has not started yet, we initialise it
         if (!this.healthInterval) {
             this.logger.debug('Starting health check timer');
-            this.healthInterval = setInterval(this.checkHealth, this.healthTimeout);
+            this.healthInterval = setInterval(() => void this.checkHealth(), this.healthTimeout);
             this.healthLastSeenDate = new Date();
             this.healthMisses = 0;
         }