feat(sensor): Available typed-input for sensor and binary_sensor - #2041
feat(sensor): Available typed-input for sensor and binary_sensor#2041Swamp-Ig wants to merge 8 commits into
Conversation
Remove the duplicate @vuepress/helper snapshot that broke --frozen-lockfile, bump prettier to the 3.9.x CI was already resolving under ^3.8.1, freeze installs in workflows, and pin format-docs to the same prettier version. Closes zachowj#2036
Probe first for old companions that reject unknown keys, then announce contrib_version when companion is 4.2.4+.
There was a problem hiding this comment.
Pull request overview
Adds an explicit Available typed-input to the Sensor and Binary Sensor entity nodes so flows can mark Home Assistant entities available/unavailable without abusing special state values, while maintaining compatibility with older Node-RED Companion versions via version/capability gating.
Changes:
- Adds
available/availableTypeconfiguration + editor UI for sensor and binary_sensor nodes, plus runtime handling for availability-only / partial updates and “Unavailable” node status. - Introduces helper utilities for availability parsing + companion version capability checks, and extends entity integration payloads + resend snapshot to include
available. - Updates docs and CI/tooling (prettier pin, frozen lockfile installs) and adds Vitest unit/integration coverage for the new behavior.
Reviewed changes
Copilot reviewed 40 out of 41 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| test/unit/nodes/binary-sensor/inputSchema.test.ts | Validates schema rules for availability-only updates and required Available config fields. |
| test/unit/helpers/utils.test.ts | Adds unit coverage for parseAvailableValue coercion/rejection behavior. |
| test/unit/helpers/exposed-settings.test.ts | Updates expected exposed schema version for sensor nodes. |
| test/unit/helpers/entityAvailable.test.ts | Adds unit tests for default-Available detection and companion capability gating. |
| test/unit/editor/convert-entity.test.ts | Ensures entity conversion sets version and Available defaults. |
| test/unit/common/status/Status.test.ts | Adds coverage for new setUnavailable status styling. |
| test/integration/sensor-availability.test.ts | Integration coverage for sensor availability, gating, and partial-update/no-op behavior. |
| test/integration/binary-sensor-availability.test.ts | Integration coverage for binary_sensor availability and partial-update/no-op behavior. |
| test/helpers/controllerTestHarness.ts | Adds controller harness utilities for integration tests (mock RED, HA client, integration). |
| src/nodes/sensor/migrations.ts | Adds v1 migration defaults for Available fields on sensor nodes. |
| src/nodes/sensor/locale.json | Adds “Available” label and updates resend label text. |
| src/nodes/sensor/editor.ts | Adds Available typed-input field, types, and companion validation/warning hook. |
| src/nodes/sensor/editor.html | Adds editor form row for Available typed-input. |
| src/nodes/entity-config/locale.json | Updates resend label to include availability. |
| src/nodes/binary-sensor/migrations.ts | Adds v1 migration defaults for Available fields on binary-sensor nodes. |
| src/nodes/binary-sensor/locale.json | Adds “Available” label and updates resend label text. |
| src/nodes/binary-sensor/index.ts | Adds Available inputs + schema changes to permit state-less updates. |
| src/nodes/binary-sensor/editor.ts | Adds Available typed-input field, types, and companion validation/warning hook. |
| src/nodes/binary-sensor/editor.html | Adds editor form row for Available typed-input. |
| src/homeAssistant/Websocket.ts | Adds contrib-version announce step in nodered/version handshake (gated by companion version). |
| src/helpers/utils.ts | Adds parseAvailableValue coercion helper modeled on HA bool vocabulary subset. |
| src/helpers/entityAvailable.ts | Adds helpers for default Available detection and companion capability checks. |
| src/editor/exposenode.ts | Adds editor-side validation + warning UI for companion version requirements. |
| src/editor/convert-entity.ts | Ensures converted entity nodes get version bump + Available defaults. |
| src/const.ts | Introduces minimum companion version constants for handshake and entity availability. |
| src/common/status/Status.ts | Adds setUnavailable status method (yellow ring). |
| src/common/status/locale.json | Adds status locale keys for companion gating, invalid input, and unavailable. |
| src/common/services/StorageService.ts | Extends last-payload snapshot typing to optionally include available. |
| src/common/integration/UnidirectionalEntityIntegration.ts | Adds available to discovery/entity payloads, supports omitting fields, gates by companion version, and extends resend snapshot merge semantics. |
| src/common/errors/locale.json | Adds localized errors for invalid Available values and minimum companion requirement. |
| src/common/controllers/SensorBaseController.ts | Implements Available resolution/coercion, partial updates, gating rules, and Unavailable status behavior. |
| pnpm-lock.yaml | Updates lockfile for prettier pin and removes duplicate snapshot entry. |
| package.json | Pins prettier dependency version. |
| docs/node/sensor.md | Documents Available and partial-update semantics for sensor nodes. |
| docs/node/entity.md | Updates resend wording to include available. |
| docs/node/entity-config.md | Updates resend wording to include available. |
| docs/node/binary-sensor.md | Documents Available and partial-update semantics for binary_sensor nodes. |
| .github/workflows/publish.yml | Uses pnpm install --frozen-lockfile for publish workflow. |
| .github/workflows/format-docs.yml | Pins prettier version used by docs formatting workflow. |
| .github/workflows/documentation.yml | Uses pnpm install --frozen-lockfile for docs build workflow. |
| .github/workflows/ci.yml | Uses pnpm install --frozen-lockfile across CI jobs. |
Files not reviewed (1)
- pnpm-lock.yaml: Generated file
|
@zachowj could you kindly turn off forced copilot reviews? I have a pretty limited credits. |
Not sure when that got flipped on but it's off for both repos now. |
|
@zachowj thanks! Otherwise I'm pretty happy with everything 😁 Let me know if there's any issues. I thought a lot about state, availability, and attributes being independent updates. I figured this way was the most flexible and users could still manage them as a group if they really wanted to. The set of attributes aren't independent however, they'll be updated together as a map. I figured allowing independent updates could be the next step if we wanted, I can think of some use cases where this could make sense. The only real thing that might be a breaking change is Unknown states no longer stand in for unavailable. This is more semantically in sync with HA general practice anyway though. |
|
At first glance, everything looks good to go. My plan is to spend some time testing everything this weekend, and if all goes well, I'll merge it. |
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
|
@zachowj Awesome! I did some fairly extensive test cases as well as testing stuff by hand, but definitely see if you can break it. If you can think of other tests outside of the test matrix I'd be interested to see. Hopefully there's nothing I've missed! If you merge this one, then #2040 and #2039 can be closed as they're incorporated in this anyhow. (same for the companion, there's one stacked PR there though). |
Resolve conflicts: take postcss ^8.5.23 from main; keep COMPANION_MIN_VERSION_ENTITY_AVAILABLE for availability gating.
Adds configurable entity Available for sensor and binary_sensor nodes, so flows can mark HA entities truly unavailable instead of hacking
state: "unknown"/null(which breaks numeric sensors). Zach accepted the design in Discussion #2029. Long-standing ask: companion #206, contrib #1044.Paired companion PR: zachowj/hass-node-red#409.
Summary
bool/true); coerce with HA templatebool; reject junk.available; availability-only updates; omit = hold once presence-available; yellow Unavailable node status.bool/truestill works on older companions (field omitted on the wire).Wire contract (with companion #409)
Once contrib has announced a package version (presence-available):
available: true|false→ set availabilityavailableomitted → leave availability unchanged (do not invent available fromstate)Default Available =
bool/truemeans every message carriesavailable: true(today’s always-available behaviour). Custom Available paths own reconnect/restart; Resend state, attributes and available restores the last snapshot.Stacking note
Depends on #2039 (version handshake), which currently also carries #2040’s lockfile/CI commit. Base is
mainso GitHub shows those commits until they merge; this PR’s own commits are the four availability ones on top. Fine to merge #2040/#2039 first, or skip intermediates and merge this alone — it carries them.Test plan
Smoke matrix
Repeat behavioural rows for sensor and binary_sensor unless noted. Auto = vitest / companion pytest; Manual = hand smoke.
Lifecycle / discovery
Editor / upgrade
Defaults / msg / coerce / override
Setup for M*: Available =
msg→payload.connected(or similar).S1(+ binary)M6/M7parseAvailableValueunitResend
Version mismatch
V3Out of scope