homebridge-plugin-utils 1.35.0 → 2.1.0

package/dist/mqttClient.js

@@ -0,0 +1,433 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * mqttClient.ts: Signal-driven MQTT client for Homebridge plugins.
+ */
+/**
+ * AsyncDisposable MQTT client whose connection lifetime is a composed {@link AbortSignal}.
+ *
+ * The client wraps the underlying MQTT.js connection in the same lifetime shape every other long-lived resource class in this library uses: a composed
+ * `AbortSignal`, a single `abort()` verb, and `Symbol.asyncDispose` for scope-bound ownership. Per-subscription and per-publish signals compose into the connection-
+ * level signal so that tearing down a specific handler or cancelling a single publish unwinds cleanly without touching the rest of the client.
+ *
+ * Non-abort transient disconnects continue to trigger MQTT.js's own auto-reconnect - `abort()` is specifically "this client is done for good," not "pause until
+ * further notice." Calling `abort()` (or letting a parent signal fire) ends the connection permanently via `mqtt.end(true)`, rejects any pending publishes with the
+ * signal's reason, clears all subscription state, and makes every subsequent call a no-op.
+ *
+ * Construction fails loudly on invalid broker URLs: the constructor throws with the underlying mqtt.js error attached as `cause`, so a misconfigured plugin cannot
+ * silently sit in a zombie state where every call either pretends to succeed or throws an unrelated abort error. Callers who want graceful degradation wrap the
+ * `new MqttClient(...)` call in their own try/catch.
+ *
+ * @module
+ */
+import { HbpuAbortError, composeSignals, formatErrorMessage, markHandled, onAbort, runWithAbort, waitWithSignal } from "./util.js";
+import { connect } from "mqtt";
+import util from "node:util";
+// Default reconnect interval, in seconds. A one-minute cadence gives a typical LAN broker (a mosquitto instance restarting or a brief network blip) time to come
+// back without hammering it with reconnect attempts, while still recovering well within the timescale a user would notice as "the plugin is broken."
+const MQTT_DEFAULT_RECONNECT_INTERVAL = 60;
+// Module-scope success sentinel for `subscribeSet` handler invocations. `runWithAbort` returns `null` when its composed signal fires, so we use a sentinel to
+// distinguish "user setter ran to completion" from "the invocation was cancelled." Hoisted once at module load rather than allocated per message, and declared as
+// `unique symbol` so the typed comparison below keeps its narrowing precision.
+const SUBSCRIBE_SET_OK = Symbol("mqtt:subscribeSet:ok");
+/**
+ * Route a transport-level MQTT error to the appropriate log line and signal whether the underlying transport should be ended. Pure function: no class state, no
+ * mqtt.js handles, no closure over the live client. The wiring layer in {@link MqttClient} forwards every `client.on("error", ...)` invocation through here and acts
+ * on the returned `endTransport` flag.
+ *
+ * The routing paths mirror the transport-error categories HBPU distinguishes:
+ *
+ * - `ECONNREFUSED` - the broker host is up but no listener accepts the connection. Recoverable; auto-reconnect handles it.
+ * - `ECONNRESET`   - the broker accepted then dropped the connection. Recoverable; auto-reconnect handles it.
+ * - `ENOTFOUND`    - DNS could not resolve the broker hostname. Non-recoverable - retrying the same hostname will keep failing - so we end the transport permanently
+ *                    and emit a standalone log line without the retry-cadence suffix.
+ * - default        - any other error code (or none). Logged through the retry-cadence formatter with `util.inspect` of the error, so a future mqtt.js error code we
+ *                    did not anticipate still surfaces in the log stream rather than being silently swallowed.
+ *
+ * @param error             - The error event payload from the underlying mqtt.js client.
+ * @param log               - Logger used to emit the routed message.
+ * @param reconnectInterval - Configured reconnect interval (in seconds) used to format the retry-cadence suffix.
+ *
+ * @returns A {@link MqttBrokerErrorResult} indicating whether the wiring layer should end the transport.
+ *
+ * @category Utilities
+ */
+export function routeMqttBrokerError(error, log, reconnectInterval) {
+    const logError = (message) => {
+        log.error("MQTT Broker: %s. Will retry again in %s second%s.", message, reconnectInterval, (reconnectInterval === 1) ? "" : "s");
+    };
+    switch (error.code) {
+        case "ECONNREFUSED":
+            logError("Connection refused");
+            return { endTransport: false };
+        case "ECONNRESET":
+            logError("Connection reset");
+            return { endTransport: false };
+        case "ENOTFOUND":
+            log.error("MQTT Broker: Hostname or IP address not found.");
+            return { endTransport: true };
+        default:
+            logError(util.inspect(error, { sorted: true }));
+            return { endTransport: false };
+    }
+}
+/**
+ * Route the outcome of a `subscribeGet` response publish to the appropriate log line. Pure function: no class state, no mqtt.js handles, no closure over the live
+ * client. The wiring in {@link MqttClient.subscribeGet} forwards each `.then` / `.catch` settlement here, and tests cover both branches by calling the function
+ * directly with synthetic `{ ok: true }` and `{ ok: false, error: ... }` outcomes - bypassing the real-broker substrate where a forced QoS-0 publish failure would
+ * require contrived socket-level setup that is not worth the test-architecture complexity.
+ *
+ * @param log     - Logger that receives the routed message.
+ * @param type    - Human-readable label (the `type` argument the caller passed to `subscribeGet`).
+ * @param outcome - The publish outcome. See {@link GetterPublishOutcome}.
+ *
+ * @category Utilities
+ */
+export function logGetterPublishOutcome(log, type, outcome) {
+    if (outcome.ok) {
+        log.info("MQTT: %s status published.", type);
+        return;
+    }
+    log.error("MQTT: failed to publish %s status: %s.", type, formatErrorMessage(outcome.error));
+}
+/**
+ * Signal-driven MQTT client with automatic topic-prefix management, composed connection lifetime, and per-operation signal support.
+ *
+ * @example
+ *
+ * ```ts
+ * import { MqttClient } from "homebridge-plugin-utils";
+ *
+ * await using mqtt = new MqttClient({ brokerUrl: "mqtt://localhost:1883", log, topicPrefix: "homebridge" }, { signal: platform.signal });
+ *
+ * // A subscription that auto-unsubscribes on the per-feature signal.
+ * const feature = new AbortController();
+ *
+ * mqtt.subscribe("device1/status", (payload) => log.info("Status: %s.", payload.toString()), { signal: feature.signal });
+ *
+ * // Abort-aware publish.
+ * await mqtt.publish("device1/status", "on");
+ * ```
+ *
+ * @category Utilities
+ */
+export class MqttClient {
+    /**
+     * The composed abort signal representing this client's lifetime. Aborts exactly once when {@link MqttClient.abort} is called or when the parent signal fires.
+     */
+    signal;
+    #brokerUrl;
+    #controller;
+    #log;
+    #mqtt;
+    #reconnectInterval;
+    #subscriptions;
+    #topicPrefix;
+    #isConnected;
+    /**
+     * Construct and start a new MQTT client.
+     *
+     * Connection is initiated synchronously as part of construction; there is no separate `connect()` step. A synchronous failure from mqtt.js (typically an invalid
+     * broker URL) surfaces as an `Error` wrapping the underlying cause, so a misconfigured plugin fails loudly instead of living in a zombie state. Network-level
+     * failures (an unreachable broker reachable by a valid URL) do not throw - they surface asynchronously through the client's `error` event, are logged, and trigger
+     * mqtt.js's built-in auto-reconnect until {@link MqttClient.abort} or a parent signal ends the client for good. A pre-aborted parent signal still constructs
+     * a client (so `#mqtt` stays non-null) and then immediately runs the regular teardown path.
+     *
+     * @param config - Static broker / topic configuration. See {@link MqttConfig}.
+     * @param init   - Optional init options. See {@link MqttClientInit}.
+     *
+     * @throws `Error` (with the underlying mqtt.js error attached as `cause`) when mqtt.js's `connect()` fails synchronously.
+     */
+    constructor(config, init = {}) {
+        this.#brokerUrl = config.brokerUrl;
+        this.#isConnected = false;
+        this.#log = config.log;
+        this.#reconnectInterval = config.reconnectInterval ?? MQTT_DEFAULT_RECONNECT_INTERVAL;
+        this.#subscriptions = new Map();
+        this.#topicPrefix = config.topicPrefix;
+        this.#controller = new AbortController();
+        this.signal = composeSignals(init.signal, this.#controller.signal);
+        // Establish the underlying MQTT.js connection unconditionally so `#mqtt` is always a live reference by the time the constructor returns. A synchronous failure
+        // (typically URL parsing) is wrapped in an Error whose `cause` carries the original error, so callers distinguish via `error.cause` rather than matching on
+        // mqtt.js's internal message text.
+        try {
+            // We connect with `rejectUnauthorized: false` deliberately. The broker URL is user-supplied and, in the typical Homebridge deployment, points at a local
+            // LAN broker (a mosquitto instance on the same network) that is frequently fronted by a self-signed certificate with no chain to a public CA. Enforcing strict
+            // certificate-chain verification would break those common self-signed setups and force users to hand-wire a CA bundle, so we accept the broker's certificate as
+            // presented. The trust boundary here is the user's own network and their own broker, not a public endpoint, which makes this the correct posture rather than a
+            // weakening of transport security.
+            this.#mqtt = connect(this.#brokerUrl, { reconnectPeriod: this.#reconnectInterval * 1000, rejectUnauthorized: false });
+        }
+        catch (error) {
+            throw new Error("MqttClient: connection setup failed.", { cause: error });
+        }
+        this.#wireMqttEvents(this.#mqtt);
+        // Teardown convergence point. `onAbort` registers the one-shot teardown handler AND runs it synchronously when the signal is already aborted at construction
+        // time (the AbortSignal spec does not re-dispatch historical events, so bare `addEventListener` would silently skip the handler for a pre-aborted parent).
+        // Running the handler in both paths means pre-aborted construction unwinds identically to a mid-session abort - the brief mqtt.js `connect()` call above is
+        // cancelled by `end(true)` before any network work proceeds.
+        onAbort(this.signal, () => this.#teardown());
+    }
+    /**
+     * Publish `payload` to `topic`, returning a promise that resolves when the broker acknowledges the publish, or rejects on failure or abort.
+     *
+     * The topic is prefixed with the configured {@link MqttConfig.topicPrefix} before being sent; callers supply the topic tail (for example, `"device1/status"`).
+     *
+     * @param topic   - The relative topic (tail) to publish to.
+     * @param payload - The payload to publish. Buffers and strings are passed through unchanged.
+     * @param init    - Optional per-publish options. See {@link MqttPublishInit}.
+     *
+     * @returns A promise that resolves once the broker acknowledges, or rejects on error or abort.
+     */
+    async publish(topic, payload, init = {}) {
+        const composed = composeSignals(this.signal, init.signal);
+        // Short-circuit pre-aborted signals before queueing anything into mqtt.js. Without this check, a publish issued after the client has already torn down would
+        // still enqueue inside mqtt.js's internal buffer (which is already being flushed by `end(true)`), producing a phantom write.
+        composed.throwIfAborted();
+        const full = this.#expandTopic(topic);
+        this.#log.debug("MQTT publish: %s.", full);
+        // Wrap mqtt.js's callback-style publish in a promise, then race it against the composed signal through `waitWithSignal` - the canonical primitive every other
+        // signal-aware wait in this library uses. `Promise.withResolvers` is the codebase-wide pattern for callback-bridged deferreds; using it here keeps the hop from
+        // mqtt.js's callback shape to a Promise on the same primitive every other wrap in HBPU uses.
+        const { promise: ackPromise, resolve, reject } = Promise.withResolvers();
+        this.#mqtt.publish(full, payload, (error) => {
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve();
+        });
+        return waitWithSignal(ackPromise, composed);
+    }
+    /**
+     * Subscribe to `topic` with the given handler. The topic is prefixed with the configured {@link MqttConfig.topicPrefix} before being registered with the broker.
+     * Multiple handlers may subscribe to the same topic; each gets independent delivery.
+     *
+     * @param topic   - The relative topic (tail) to subscribe to.
+     * @param handler - Callback invoked with each received payload.
+     * @param init    - Optional per-subscription options. See {@link MqttSubscribeInit}.
+     */
+    subscribe(topic, handler, init = {}) {
+        // Ignore subscribes that cannot produce any effect: the client is already dead or the caller handed us a pre-aborted per-subscription signal. Early-return keeps
+        // the subscription map honest - nothing gets registered that cannot receive.
+        if (this.signal.aborted || init.signal?.aborted) {
+            return;
+        }
+        const full = this.#expandTopic(topic);
+        this.#log.debug("MQTT subscribe: %s.", full);
+        let handlers = this.#subscriptions.get(full);
+        if (!handlers) {
+            handlers = new Set();
+            this.#subscriptions.set(full, handlers);
+            // First handler on this topic: issue the wire-level subscribe. Subsequent handlers on the same topic reuse the existing broker subscription, matching the
+            // "pay once per topic" cost model the MQTT protocol naturally provides.
+            this.#mqtt.subscribe(full);
+        }
+        handlers.add(handler);
+        // Per-subscription cleanup: compose the caller's signal with the connection-level signal so either teardown path fires the listener exactly once. Attaching the
+        // listener to the composed signal (rather than to `init.signal` directly) ensures the listener auto-releases when the client aborts even if the caller never
+        // aborts their per-subscription controller - the composed signal is what prevents the closure from pinning the handler past the connection's lifetime.
+        if (init.signal) {
+            const composed = composeSignals(this.signal, init.signal);
+            onAbort(composed, () => this.#removeHandler(full, handler));
+        }
+    }
+    /**
+     * Subscribe to the `/get` child of `topic`. When a `"true"` message arrives on the get topic, the provided `getValue` callback runs and its return value is
+     * published back on the parent topic. The classic HomeKit "get" pattern, wrapped once.
+     *
+     * @param topic    - The relative topic (tail); the `/get` suffix is appended automatically.
+     * @param type     - Human-readable label used in log messages (for example, `"Temperature"`).
+     * @param getValue - Callback returning the current value as a string, invoked on each incoming `"true"` message.
+     * @param init     - Optional per-subscription options. See {@link MqttSubscribeInit}.
+     */
+    subscribeGet(topic, type, getValue, init = {}) {
+        this.subscribe(topic + "/get", (message) => {
+            const value = message.toString().toLowerCase();
+            // The get-pattern contract: only `"true"` triggers a republish. Other values (empty, `"false"`, noise) are ignored silently so the broker-side fan-out can
+            // request status without every listener responding.
+            if (value !== "true") {
+                return;
+            }
+            // Sequence both log lines through {@link logGetterPublishOutcome} so the routing between success and failure is expressible as a pure function and testable in
+            // isolation. The publish promise settles exactly once - either `.then` (success) or `.catch` (failure) runs - and each path forwards its outcome through the
+            // single routing point, keeping the log surface honest about what actually happened on the wire.
+            void this.publish(topic, getValue())
+                .then(() => logGetterPublishOutcome(this.#log, type, { ok: true }))
+                .catch((error) => logGetterPublishOutcome(this.#log, type, { error, ok: false }));
+        }, init);
+    }
+    /**
+     * Subscribe to the `/set` child of `topic`. Each incoming message invokes `setValue` with the lowercased normalized value, the raw message string, and an
+     * {@link AbortSignal} that composes the connection-level signal with the optional per-invocation `timeout`. Signal-aware setters forward that signal to cancellation-
+     * capable APIs so the setter's work actually stops when the timeout elapses or the client aborts; signal-unaware setters continue to run but the subscription slot
+     * is released either way, so a hanging setter cannot tie up the slot indefinitely.
+     *
+     * @param topic    - The relative topic (tail); the `/set` suffix is appended automatically.
+     * @param type     - Human-readable label used in log messages.
+     * @param setValue - Callback invoked with each received value. Receives three arguments: `(value, rawValue, signal)`. See {@link MqttSetHandler}.
+     * @param init     - Optional per-subscription options including a handler-invocation `timeout`. See {@link MqttSubscribeSetInit}.
+     */
+    subscribeSet(topic, type, setValue, init = {}) {
+        const timeout = init.timeout;
+        this.subscribe(topic + "/set", async (message) => {
+            const rawValue = message.toString();
+            const value = rawValue.toLowerCase();
+            try {
+                // `runWithAbort` composes the connection-level signal with the optional per-invocation timeout and passes the composed signal to its factory. We forward that
+                // signal into the user's setter so signal-aware setters can actually cancel in-flight work on timeout or teardown. A module-level sentinel distinguishes "user
+                // setter ran to completion" from "runWithAbort returned null because the signal aborted," keeping cancellation on the `warn` log path rather than the error
+                // path. The `{ signal, timeout?: number }` option form accepts `timeout: undefined`, so a single call shape covers both the with-timeout and without-timeout
+                // cases.
+                const result = await runWithAbort(async (setterSignal) => {
+                    await setValue(value, rawValue, setterSignal);
+                    return SUBSCRIBE_SET_OK;
+                }, { signal: this.signal, timeout });
+                if (result !== SUBSCRIBE_SET_OK) {
+                    this.#log.warn("MQTT: set handler for %s was cancelled before completion.", type);
+                    return;
+                }
+                this.#log.info("MQTT: set message received for %s: %s.", type, value);
+            }
+            catch (error) {
+                this.#log.error("MQTT: error setting %s to %s: %s.", type, value, formatErrorMessage(error));
+            }
+        }, init);
+    }
+    /**
+     * Unsubscribe all handlers for the specified `(id, topic)` tuple. Reconstructs the topic using the configured {@link MqttConfig.topicPrefix}, removes the
+     * subscription from the internal map, and issues the wire-level unsubscribe. Preserved as a separate imperative verb for the mid-session feature-toggle pattern
+     * where the caller has the `(id, topic)` tuple but never retained a dedicated controller.
+     *
+     * Deliberately does not accept a `{ signal }` option: unsubscribe is synchronous and has nothing to cancel, and exposing a vestigial signal would suggest a
+     * cancellation semantic the method cannot deliver. Callers composing teardown through a signal remove handlers by aborting the per-subscription signal they passed
+     * to `subscribe*` instead.
+     *
+     * @param id    - The device or accessory identifier portion of the topic. An empty string short-circuits the whole call.
+     * @param topic - The topic tail relative to the id.
+     */
+    unsubscribe(id, topic) {
+        // No-op on an aborted client: the wire-level subscribe has already been released by `#teardown`, and the subscription map is empty. Checking the signal up front
+        // lets subsequent `this.#mqtt` accesses run unguarded.
+        if (this.signal.aborted || !id) {
+            return;
+        }
+        const full = this.#expandTopic(id + "/" + topic);
+        this.#subscriptions.delete(full);
+        this.#mqtt.unsubscribe(full);
+    }
+    /**
+     * Abort the client and tear the connection down. Defaults to `HbpuAbortError("shutdown")` when no reason is supplied; explicit reasons pass through unchanged.
+     *
+     * Safe to call more than once. After this runs, every subsequent `publish`, `subscribe*`, or `unsubscribe` call is a no-op.
+     *
+     * @param reason - Optional abort reason. Typically an {@link HbpuAbortError}; platform errors also interoperate by convention.
+     */
+    abort(reason) {
+        if (this.aborted) {
+            return;
+        }
+        this.#controller.abort(reason ?? new HbpuAbortError("shutdown"));
+    }
+    /**
+     * `AsyncDisposable` implementation. Aborts the client (defaulting to `"shutdown"`), which tears the MQTT connection down and rejects any pending publishes through
+     * the regular teardown path.
+     *
+     * @returns A promise that resolves once teardown has been scheduled. MQTT.js's `end(true)` completes synchronously for userland purposes, so the awaited microtask
+     *          is all the ordering the caller needs.
+     */
+    async [Symbol.asyncDispose]() {
+        this.abort();
+    }
+    /**
+     * `true` once `this.signal` has aborted. Derived from the signal; no independent state.
+     */
+    get aborted() {
+        return this.signal.aborted;
+    }
+    // Wire up the MQTT.js event handlers that drive message dispatch, connection lifecycle logging, and error escalation. Extracted into a helper so the constructor
+    // reads as a linear flow (set up state -> compose signal -> connect -> wire events).
+    #wireMqttEvents(client) {
+        client.on("connect", () => {
+            this.#isConnected = true;
+            // The replace strips the password from the broker URL's `user:password@host` userinfo before logging, so credentials never reach the log stream. The capture
+            // groups preserve the scheme-plus-username prefix and the `@host` suffix while swapping only the password segment for REDACTED.
+            this.#log.info("MQTT Broker: Connected to %s (topic: %s).", this.#brokerUrl.replace(/^(.*:\/\/.*:)(.*)(@.*)$/, "$1REDACTED$3"), this.#topicPrefix);
+        });
+        client.on("close", () => {
+            // Only log a disconnect when we had previously connected - otherwise we would spam the log on every failed connect attempt during a retry loop. Tracking
+            // `#isConnected` as an edge flag (true on connect, false on close) captures the transition cleanly; mqtt.js's own `.connected` property is already `false` by
+            // the time this listener fires, so it cannot answer the "were we previously connected?" question on its own.
+            if (!this.#isConnected) {
+                return;
+            }
+            this.#isConnected = false;
+            this.#log.info("MQTT Broker: Connection closed.");
+        });
+        client.on("message", (topic, message) => {
+            const handlers = this.#subscriptions.get(topic);
+            if (!handlers) {
+                return;
+            }
+            // Snapshot the handler set before iterating so a handler that removes itself (or a sibling) mid-dispatch cannot alter which handlers this dispatch pass
+            // invokes. Iterating the live Set directly would still be spec-correct - Set iteration order and hole-skipping on delete are well-defined - but it would make
+            // the invocation set implicit and mutation-order-dependent. The snapshot cost is O(n) in handlers per topic, same as the dispatch itself, so the overhead is
+            // negligible. Sync handlers run inline so their effects are observable on the calling turn (matching
+            // EventEmitter's dispatch model and the public contract these tests assert); only the per-handler error handling is split between the sync and async legs,
+            // both of which route through the same `logHandlerError` so the log surface is single-source-of-truth. One bad handler logs but does not destabilize the
+            // connection or skip its siblings.
+            const logHandlerError = (err) => {
+                this.#log.error("MQTT: handler for %s threw: %s.", topic, formatErrorMessage(err));
+            };
+            for (const handler of [...handlers]) {
+                try {
+                    const result = handler(message);
+                    if (result instanceof Promise) {
+                        void markHandled(result.catch(logHandlerError));
+                    }
+                }
+                catch (err) {
+                    logHandlerError(err);
+                }
+            }
+        });
+        client.on("error", (error) => {
+            // Route the error through the pure {@link routeMqttBrokerError} helper, which selects the right log line for each known errno code (and the default branch for
+            // unknown codes). The wiring layer's only side-effect responsibility is acting on the returned `endTransport` flag - the routing logic is testable in isolation
+            // through direct invocation against synthetic errors, so this `client.on("error", ...)` callback stays a thin adapter from the mqtt.js event surface to the
+            // pure routing function.
+            const result = routeMqttBrokerError(error, this.#log, this.#reconnectInterval);
+            if (result.endTransport) {
+                this.#mqtt.end(true);
+            }
+        });
+    }
+    // Remove a single handler from a topic's subscription set. When the last handler leaves, the underlying MQTT subscription is dropped so idle topics do not continue
+    // consuming broker bandwidth. Safe to call for handlers that were never registered (silently no-ops) and safe to call after the connection has aborted (the
+    // subscription map is cleared by `#teardown`, so the initial `!handlers` check short-circuits before any `#mqtt` interaction).
+    #removeHandler(full, handler) {
+        const handlers = this.#subscriptions.get(full);
+        if (!handlers) {
+            return;
+        }
+        handlers.delete(handler);
+        if (handlers.size === 0) {
+            this.#subscriptions.delete(full);
+            this.#mqtt.unsubscribe(full);
+        }
+    }
+    // Expand a relative topic tail into the full broker-facing topic. Always concatenates with the configured prefix; the caller is responsible for any id structure
+    // inside the tail. Keeping this as a single small helper means every publish / subscribe site goes through identical expansion logic, avoiding drift.
+    #expandTopic(topic) {
+        return this.#topicPrefix + "/" + topic;
+    }
+    // Single teardown convergence point, fired exactly once when `this.signal` aborts. Clears the subscription map so multi-consumer fan-out stops delivering messages
+    // on the way out, then ends the MQTT.js connection with `force = true` so any in-flight publish / subscribe packets are dropped rather than awaited - the client is
+    // unambiguously done, and the underlying library's reconnect logic exits permanently. The `#mqtt` reference is not nulled: callers never reach `#mqtt` accesses
+    // when the signal is aborted (every public method short-circuits on `signal.aborted`), and keeping the reference preserves the `readonly #mqtt: MqttJsClient`
+    // guarantee that lets TypeScript drop every non-null assertion in the live paths.
+    #teardown() {
+        this.#subscriptions.clear();
+        this.#mqtt.end(true);
+    }
+}
+//# sourceMappingURL=mqttClient.js.map

package/dist/mqttClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mqttClient.js","sourceRoot":"","sources":["../src/mqttClient.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,kBAAkB,EAAE,WAAW,EAAE,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAGnI,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAC/B,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,iKAAiK;AACjK,qJAAqJ;AACrJ,MAAM,+BAA+B,GAAG,EAAE,CAAC;AAE3C,8JAA8J;AAC9J,kKAAkK;AAClK,+EAA+E;AAC/E,MAAM,gBAAgB,GAAkB,MAAM,CAAC,sBAAsB,CAAC,CAAC;AA2FvE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAA4B,EAAE,GAA4B,EAAE,iBAAyB;IAExH,MAAM,QAAQ,GAAG,CAAC,OAAe,EAAQ,EAAE;QAEzC,GAAG,CAAC,KAAK,CAAC,mDAAmD,EAAE,OAAO,EAAE,iBAAiB,EAAE,CAAC,iBAAiB,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACnI,CAAC,CAAC;IAEF,QAAO,KAAK,CAAC,IAAI,EAAE,CAAC;QAElB,KAAK,cAAc;YAEjB,QAAQ,CAAC,oBAAoB,CAAC,CAAC;YAE/B,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC;QAEjC,KAAK,YAAY;YAEf,QAAQ,CAAC,kBAAkB,CAAC,CAAC;YAE7B,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC;QAEjC,KAAK,WAAW;YAEd,GAAG,CAAC,KAAK,CAAC,gDAAgD,CAAC,CAAC;YAE5D,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;QAEhC;YAEE,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;YAEhD,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC;IACnC,CAAC;AACH,CAAC;AAWD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAA4B,EAAE,IAAY,EAAE,OAA6B;IAE/G,IAAG,OAAO,CAAC,EAAE,EAAE,CAAC;QAEd,GAAG,CAAC,IAAI,CAAC,4BAA4B,EAAE,IAAI,CAAC,CAAC;QAE7C,OAAO;IACT,CAAC;IAED,GAAG,CAAC,KAAK,CAAC,wCAAwC,EAAE,IAAI,EAAE,kBAAkB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;AAC/F,CAAC;AA6CD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAO,UAAU;IAErB;;OAEG;IACa,MAAM,CAAc;IAE3B,UAAU,CAAS;IACnB,WAAW,CAAkB;IAC7B,IAAI,CAA0B;IAC9B,KAAK,CAAe;IACpB,kBAAkB,CAAS;IAC3B,cAAc,CAAgC;IAC9C,YAAY,CAAS;IAC9B,YAAY,CAAU;IAEtB;;;;;;;;;;;;;OAaG;IACH,YAAmB,MAAkB,EAAE,OAAuB,EAAE;QAE9D,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC;QACvB,IAAI,CAAC,kBAAkB,GAAG,MAAM,CAAC,iBAAiB,IAAI,+BAA+B,CAAC;QACtF,IAAI,CAAC,cAAc,GAAG,IAAI,GAAG,EAAE,CAAC;QAChC,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,WAAW,CAAC;QAEvC,IAAI,CAAC,WAAW,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,IAAI,CAAC,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QAEnE,+JAA+J;QAC/J,4JAA4J;QAC5J,mCAAmC;QACnC,IAAI,CAAC;YAEH,yJAAyJ;YACzJ,+JAA+J;YAC/J,gKAAgK;YAChK,+JAA+J;YAC/J,mCAAmC;YACnC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,eAAe,EAAE,IAAI,CAAC,kBAAkB,GAAG,IAAI,EAAE,kBAAkB,EAAE,KAAK,EAAE,CAAC,CAAC;QACxH,CAAC;QAAC,OAAM,KAAK,EAAE,CAAC;YAEd,MAAM,IAAI,KAAK,CAAC,sCAAsC,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5E,CAAC;QAED,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAEjC,6JAA6J;QAC7J,2JAA2J;QAC3J,4JAA4J;QAC5J,6DAA6D;QAC7D,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED;;;;;;;;;;OAUG;IACI,KAAK,CAAC,OAAO,CAAC,KAAa,EAAE,OAAwB,EAAE,OAAwB,EAAE;QAEtF,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAE1D,6JAA6J;QAC7J,6HAA6H;QAC7H,QAAQ,CAAC,cAAc,EAAE,CAAC;QAE1B,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QAEtC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,mBAAmB,EAAE,IAAI,CAAC,CAAC;QAE3C,8JAA8J;QAC9J,gKAAgK;QAChK,6FAA6F;QAC7F,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,GAA+B,OAAO,CAAC,aAAa,EAAE,CAAC;QAErG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YAE1C,IAAG,KAAK,EAAE,CAAC;gBAET,MAAM,CAAC,KAAK,CAAC,CAAC;gBAEd,OAAO;YACT,CAAC;YAED,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC,CAAC;QAEH,OAAO,cAAc,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IAC9C,CAAC;IAED;;;;;;;OAOG;IACI,SAAS,CAAC,KAAa,EAAE,OAAoB,EAAE,OAA0B,EAAE;QAEhF,iKAAiK;QACjK,6EAA6E;QAC7E,IAAG,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;YAE/C,OAAO;QACT,CAAC;QAED,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QAEtC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,qBAAqB,EAAE,IAAI,CAAC,CAAC;QAE7C,IAAI,QAAQ,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAE7C,IAAG,CAAC,QAAQ,EAAE,CAAC;YAEb,QAAQ,GAAG,IAAI,GAAG,EAAE,CAAC;YACrB,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;YAExC,0JAA0J;YAC1J,wEAAwE;YACxE,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;QAED,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAEtB,gKAAgK;QAChK,6JAA6J;QAC7J,uJAAuJ;QACvJ,IAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YAEf,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;YAE1D,OAAO,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;QAC9D,CAAC;IACH,CAAC;IAED;;;;;;;;OAQG;IACI,YAAY,CAAC,KAAa,EAAE,IAAY,EAAE,QAAwB,EAAE,OAA0B,EAAE;QAErG,IAAI,CAAC,SAAS,CAAC,KAAK,GAAG,MAAM,EAAE,CAAC,OAAe,EAAE,EAAE;YAEjD,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,WAAW,EAAE,CAAC;YAE/C,2JAA2J;YAC3J,oDAAoD;YACpD,IAAG,KAAK,KAAK,MAAM,EAAE,CAAC;gBAEpB,OAAO;YACT,CAAC;YAED,+JAA+J;YAC/J,6JAA6J;YAC7J,iGAAiG;YACjG,KAAK,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,QAAQ,EAAE,CAAC;iBACjC,IAAI,CAAC,GAAG,EAAE,CAAC,uBAAuB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;iBAClE,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE,CAAC,uBAAuB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;QAC/F,CAAC,EAAE,IAAI,CAAC,CAAC;IACX,CAAC;IAED;;;;;;;;;;OAUG;IACI,YAAY,CAAC,KAAa,EAAE,IAAY,EAAE,QAAwB,EAAE,OAA6B,EAAE;QAExG,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAE7B,IAAI,CAAC,SAAS,CAAC,KAAK,GAAG,MAAM,EAAE,KAAK,EAAE,OAAe,EAAE,EAAE;YAEvD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;YACpC,MAAM,KAAK,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC;YAErC,IAAI,CAAC;gBAEH,8JAA8J;gBAC9J,+JAA+J;gBAC/J,4JAA4J;gBAC5J,6JAA6J;gBAC7J,SAAS;gBACT,MAAM,MAAM,GAAG,MAAM,YAAY,CAA0B,KAAK,EAAE,YAAY,EAAE,EAAE;oBAEhF,MAAM,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC;oBAE9C,OAAO,gBAAgB,CAAC;gBAC1B,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;gBAErC,IAAG,MAAM,KAAK,gBAAgB,EAAE,CAAC;oBAE/B,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,2DAA2D,EAAE,IAAI,CAAC,CAAC;oBAElF,OAAO;gBACT,CAAC;gBAED,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,wCAAwC,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;YACxE,CAAC;YAAC,OAAM,KAAK,EAAE,CAAC;gBAEd,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,mCAAmC,EAAE,IAAI,EAAE,KAAK,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC;YAC/F,CAAC;QACH,CAAC,EAAE,IAAI,CAAC,CAAC;IACX,CAAC;IAED;;;;;;;;;;;OAWG;IACI,WAAW,CAAC,EAAU,EAAE,KAAa;QAE1C,iKAAiK;QACjK,uDAAuD;QACvD,IAAG,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,EAAE,EAAE,CAAC;YAE9B,OAAO;QACT,CAAC;QAED,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,CAAC,EAAE,GAAG,GAAG,GAAG,KAAK,CAAC,CAAC;QAEjD,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACjC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,MAAgB;QAE3B,IAAG,IAAI,CAAC,OAAO,EAAE,CAAC;YAEhB,OAAO;QACT,CAAC;QAED,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,MAAM,IAAI,IAAI,cAAc,CAAC,UAAU,CAAC,CAAC,CAAC;IACnE,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC;QAEhC,IAAI,CAAC,KAAK,EAAE,CAAC;IACf,CAAC;IAED;;OAEG;IACH,IAAW,OAAO;QAEhB,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;IAC7B,CAAC;IAED,iKAAiK;IACjK,qFAAqF;IACrF,eAAe,CAAC,MAAoB;QAElC,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE;YAExB,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;YAEzB,6JAA6J;YAC7J,gIAAgI;YAChI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,2CAA2C,EAAE,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,yBAAyB,EAAE,cAAc,CAAC,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;QACrJ,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YAEtB,yJAAyJ;YACzJ,8JAA8J;YAC9J,6GAA6G;YAC7G,IAAG,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;gBAEtB,OAAO;YACT,CAAC;YAED,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC;YAC1B,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,iCAAiC,CAAC,CAAC;QACpD,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,KAAa,EAAE,OAAe,EAAE,EAAE;YAEtD,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YAEhD,IAAG,CAAC,QAAQ,EAAE,CAAC;gBAEb,OAAO;YACT,CAAC;YAED,wJAAwJ;YACxJ,8JAA8J;YAC9J,6JAA6J;YAC7J,qGAAqG;YACrG,2JAA2J;YAC3J,yJAAyJ;YACzJ,mCAAmC;YACnC,MAAM,eAAe,GAAG,CAAC,GAAY,EAAQ,EAAE;gBAE7C,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,iCAAiC,EAAE,KAAK,EAAE,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC;YACrF,CAAC,CAAC;YAEF,KAAI,MAAM,OAAO,IAAI,CAAC,GAAG,QAAQ,CAAC,EAAE,CAAC;gBAEnC,IAAI,CAAC;oBAEH,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;oBAEhC,IAAG,MAAM,YAAY,OAAO,EAAE,CAAC;wBAE7B,KAAK,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,CAAC;oBAClD,CAAC;gBACH,CAAC;gBAAC,OAAM,GAAG,EAAE,CAAC;oBAEZ,eAAe,CAAC,GAAG,CAAC,CAAC;gBACvB,CAAC;YACH,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAY,EAAE,EAAE;YAElC,+JAA+J;YAC/J,gKAAgK;YAChK,4JAA4J;YAC5J,yBAAyB;YACzB,MAAM,MAAM,GAAG,oBAAoB,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,kBAAkB,CAAC,CAAC;YAE/E,IAAG,MAAM,CAAC,YAAY,EAAE,CAAC;gBAEvB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACvB,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED,oKAAoK;IACpK,4JAA4J;IAC5J,+HAA+H;IAC/H,cAAc,CAAC,IAAY,EAAE,OAAoB;QAE/C,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAE/C,IAAG,CAAC,QAAQ,EAAE,CAAC;YAEb,OAAO;QACT,CAAC;QAED,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAEzB,IAAG,QAAQ,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YAEvB,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACjC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IAED,iKAAiK;IACjK,sJAAsJ;IACtJ,YAAY,CAAC,KAAa;QAExB,OAAO,IAAI,CAAC,YAAY,GAAG,GAAG,GAAG,KAAK,CAAC;IACzC,CAAC;IAED,mKAAmK;IACnK,oKAAoK;IACpK,gKAAgK;IAChK,8JAA8J;IAC9J,kFAAkF;IAClF,SAAS;QAEP,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,CAAC;QAC5B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACvB,CAAC;CACF"}

package/dist/service.d.ts

@@ -4,18 +4,38 @@
  * @module
  */
 import type { PlatformAccessory, Service, WithUUID } from "homebridge";
-import { type Nullable } from "./util.js";
+import type { Nullable } from "./util.ts";
+/**
+ * The constructor shape {@link acquireService} expects for a Service subclass. Every HAP Service subclass (Lightbulb, Switch, Television, ...) satisfies both halves
+ * of this intersection naturally:
+ *
+ * - `WithUUID<typeof Service>` - provides the static `UUID` property AND assignability to HAP's `getService` / `getServiceById` lookup APIs that require this exact
+ *   shape.
+ * - `new (displayName?: string, subtype?: string) => T` - the actual runtime constructor signature every Service subclass exposes; supersedes the BASE Service
+ *   class's `(displayName, UUID, subtype?)` signature that the wider `WithUUID<typeof Service>` would otherwise surface.
+ *
+ * Intersecting both shapes lets the function invoke `new serviceType(sanitized, subtype)` against an honest type-checked signature without any cast or non-null
+ * assertion.
+ *
+ * @typeParam T - The concrete Service subclass produced by the constructor. Inferred from the call site so callers receive the specific subclass type back.
+ *
+ * @category Accessory
+ */
+export type AcquireServiceTarget<T extends Service = Service> = WithUUID<typeof Service> & (new (displayName?: string, subtype?: string) => T);
 /**
  * Utility method that either creates a new service on an accessory if needed, or returns an existing one. Optionally, it executes a callback to initialize a new
  * service instance. Additionally, the various name characteristics of the service are set to the specified name, and optionally added if necessary.
  *
+ * @typeParam T          - The concrete Service subclass being acquired. Inferred from `serviceType` so callers receive the specific subclass type back rather than
+ *                         the wider `Service` type.
  * @param accessory       - The Homebridge accessory to check or modify.
- * @param serviceType     - The type of service to instantiate or retrieve.
+ * @param serviceType     - The type of service to instantiate or retrieve. Must be a HAP Service subclass with the standard `(displayName?, subtype?)` constructor;
+ *                         see {@link AcquireServiceTarget}.
  * @param name            - Name to be displayed to the end user for this service.
  * @param subtype         - Optional service subtype to uniquely identify the service.
  * @param onServiceCreate - Optional callback invoked only when a new service is created, receiving the new service as its argument.
  *
- * @returns Returns the created or retrieved service, or `null` if service creation failed.
+ * @returns Returns the created or retrieved service. Construction failures throw rather than returning `null`.
  *
  * @remarks
  * This method ensures that the service's display name and available name characteristics are updated to the specified name. If `onServiceCreate` is provided,
@@ -25,10 +45,11 @@ import { type Nullable } from "./util.js";
  *
  * @example
  * ```typescript
- * // Example: Ensure a Lightbulb service exists with a user-friendly name, and initialize it if newly created.
- * const lightbulbService = acquireService(accessory, hap.Service.Lightbulb, "Living Room Lamp", undefined, (svc: Service): void => {
+ * // Example: Ensure a Lightbulb service exists with a user-friendly name, and initialize it if newly created. The return type is narrowed to `Lightbulb | null`,
+ * // so callers can invoke subclass-specific behavior on the result without casts.
+ * const lightbulbService = acquireService(accessory, hap.Service.Lightbulb, "Living Room Lamp", undefined, (svc): void => {
  *
- *   // Called only if the service is newly created.
+ *   // Called only if the service is newly created. `svc` is typed as `Lightbulb` here.
  *   svc.setCharacteristic(hap.Characteristic.On, false);
  * });
  *
@@ -39,11 +60,11 @@ import { type Nullable } from "./util.js";
  * }
  * ```
  *
- * @see setServiceName — updates the newly created (or existing) service’s name-related characteristics.
- * @see validService — validate or prune services after acquisition.
+ * @see setServiceName - updates the newly created (or existing) service's name-related characteristics.
+ * @see validService - validate or prune services after acquisition.
  * @category Accessory
  */
-export declare function acquireService(accessory: PlatformAccessory, serviceType: WithUUID<typeof Service>, name: string, subtype?: string, onServiceCreate?: (svc: Service) => void): Nullable<Service>;
+export declare function acquireService<T extends Service>(accessory: PlatformAccessory, serviceType: AcquireServiceTarget<T>, name: string, subtype?: string, onServiceCreate?: (svc: T) => void): Nullable<T>;
 /**
  * Validates whether a specific service should exist on the given accessory, removing the service if it fails validation.
  *
@@ -74,17 +95,44 @@ export declare function acquireService(accessory: PlatformAccessory, serviceType
  * validService(accessory, Service.Switch, (hasService) => hasService || config.enableSwitch);
  * ```
  *
- * @see acquireService — to add or retrieve services.
+ * @see acquireService - to add or retrieve services.
  * @category Accessory
  */
 export declare function validService(accessory: PlatformAccessory, serviceType: WithUUID<typeof Service>, validate: boolean | ((hasService: boolean) => boolean), subtype?: string): boolean;
 /**
- * Retrieves the primary name of a service, preferring the ConfiguredName characteristic over the Name characteristic.
+ * Build a `validService` predicate for a service gated on a hardware capability and a user toggle, applying an additive-eager / subtractive-conservative asymmetry
+ * between the two: the user `toggle` is absolute - when false, the service is removed - while the hardware `capability` is conservative - an existing service is kept
+ * through a transient capability-false, and a new service is created only when the capability reports.
+ *
+ * @param options - The `capability` and `toggle` inputs for the gate.
+ *
+ * @returns A `validService` function-form predicate, `(hasService) => toggle && (hasService || capability)`.
+ *
+ * @remarks
+ * Pass the result as `validService`'s `validate` argument. The asymmetry keeps a capability-gated service from being removed during a transient window in which the
+ * device under-reports its capability, while still honoring a user who disables the service. A service with no user toggle should gate on its capability directly.
+ *
+ * @example
+ * ```typescript
+ * // Keep the service while its user toggle is on, add it when the capability reports, and keep an existing one through a transient capability-false.
+ * validService(accessory, Service.Switch, capabilityGate({ capability: deviceReportsFeature, toggle: config.enableSwitch }));
+ * ```
+ *
+ * @see validService - consumes the returned predicate.
+ * @category Accessory
+ */
+export declare function capabilityGate({ capability, toggle }: {
+    capability: boolean;
+    toggle: boolean;
+}): (hasService: boolean) => boolean;
+/**
+ * Retrieves the primary name of a service, preferring the ConfiguredName characteristic over the Name characteristic. This is a pure read - it never mutates the
+ * service.
  *
  * @param service - The service from which to retrieve the name.
- * @returns The configured or display name of the service, or `undefined` if neither is set.
+ * @returns The configured or display name of the service, or `undefined` if neither characteristic is present or set.
  *
- * @see setServiceName — to update the current name on a service.
+ * @see setServiceName - to update the current name on a service.
  * @category Accessory
  */
 export declare function getServiceName(service?: Service): string | undefined;
@@ -98,8 +146,9 @@ export declare function getServiceName(service?: Service): string | undefined;
  * This function ensures the name is validated, updates the service's `displayName`, and sets the `ConfiguredName` and `Name`
  * characteristics when supported by the service type.
  *
- * @see acquireService — to add or retrieve services.
- * @see getServiceName — to retrieve the current name set on a service.
+ * @see acquireService - to add or retrieve services.
+ * @see getServiceName - to retrieve the current name set on a service.
  * @category Accessory
  */
 export declare function setServiceName(service: Service, name: string): void;
+//# sourceMappingURL=service.d.ts.map