@digital-alchemy/hass 25.11.16 → 25.11.23

package/src/services/reference.service.mts

@@ -1,4 +1,4 @@
-import type { TAnyFunction, TServiceParams } from "@digital-alchemy/core";
+import type { TAnyFunction, TOffset, TServiceParams } from "@digital-alchemy/core";
 import { DOWN, NONE, sleep, UP } from "@digital-alchemy/core";
 import type { Dayjs } from "dayjs";
 import dayjs from "dayjs";
@@ -9,6 +9,7 @@ import type {
   ByIdProxy,
   ENTITY_STATE,
   HassReferenceService,
+  OnStateForOptions,
   RemoveCallback,
 } from "../helpers/index.mts";
 import { domain, perf } from "../helpers/index.mts";
@@ -86,6 +87,7 @@ export function ReferenceService({
   hass,
   logger,
   internal,
+  scheduler,
   event,
 }: TServiceParams): HassReferenceService {
   const { is } = internal.utils;
@@ -94,6 +96,9 @@ export function ReferenceService({
     entity: ENTITY,
     property: PROPERTY,
   ): Get<ENTITY_STATE<ENTITY>, PROPERTY> {
+    if (!is.string(property)) {
+      return undefined;
+    }
     const valid = ["state", "attributes", "last"].some(i => property.startsWith(i));
     if (!valid) {
       logger.error({ entity, name: proxyGetLogic, property }, `invalid property lookup`);
@@ -131,9 +136,12 @@ export function ReferenceService({
         "attributes",
         "entity_id",
         "history",
-        "last",
+        "last_changed",
+        "last_reported",
+        "last_updated",
         "nextState",
         "once",
+        "onStateFor",
         "onUpdate",
         "previous",
         "removeAllListeners",
@@ -170,8 +178,62 @@ export function ReferenceService({
       // things that shouldn't be needed: this extract
       // eslint-disable-next-line sonarjs/function-return-type
       get: (_, property: Extract<keyof ByIdProxy<ENTITY_ID>, string>) => {
+        // Handle Symbol properties (e.g., when vitest formats test output)
+        if (!is.string(property)) {
+          return undefined;
+        }
         hass.diagnostics.reference?.get_property.publish({ entity_id, property });
         switch (property) {
+          // #MARK: runAfter
+          case "onStateFor": {
+            return function ({
+              context,
+              ...options
+            }: OnStateForOptions<ENTITY_ID>): RemoveCallback {
+              let timerRemove: RemoveCallback;
+              const remove = proxy.onUpdate((new_state, old_state) => {
+                const matches = options.matches
+                  ? options.matches(new_state, old_state)
+                  : options.state === new_state.state;
+                if (!matches) {
+                  if (timerRemove) {
+                    timerRemove();
+                    timerRemove = undefined;
+                    logger.trace({ context, entity_id }, "cleared timer - state no longer matches");
+                  }
+                  return;
+                }
+
+                if (timerRemove) {
+                  logger.trace({ context, entity_id }, "timer already running, skipping");
+                  return;
+                }
+                timerRemove = scheduler.setTimeout(async () => {
+                  logger.trace(
+                    { context, entity_id, for: options.for },
+                    "timer fired - executing callback",
+                  );
+                  internal.safeExec({
+                    context,
+                    exec: async () => await options.exec(proxy),
+                  });
+                }, options.for);
+                logger.trace(
+                  { context, entity_id, for: options.for },
+                  "started timer for state condition",
+                );
+              });
+
+              return internal.removeFn(() => {
+                if (timerRemove) {
+                  timerRemove();
+                }
+                remove();
+                logger.trace({ context, entity_id }, "removed [onStateFor] listener");
+              });
+            };
+          }
+
           // #MARK: onUpdate
           case "onUpdate": {
             return (callback: TAnyFunction) => {
@@ -246,7 +308,7 @@ export function ReferenceService({
 
           // #MARK: nextState
           case "nextState": {
-            return async (timeout?: number) =>
+            return async (timeout?: TOffset) =>
               await new Promise<ENTITY_STATE<ENTITY_ID>>(async done => {
                 // - set up cleanup function
                 const remove = () => {
@@ -274,9 +336,13 @@ export function ReferenceService({
 
                 // - race!
                 let wait: ReturnType<typeof sleep>;
-                if (is.number(timeout) && timeout > NONE) {
+                if (is.undefined(timeout)) {
+                  return;
+                }
+                const duration = internal.utils.getIntervalMs(timeout);
+                if (duration > NONE) {
                   // keep track of sleep so it can be cleaned up also
-                  wait = sleep(timeout);
+                  wait = sleep(duration);
                   await wait;
                   wait = undefined;
                   if (done) {
@@ -290,10 +356,9 @@ export function ReferenceService({
 
           // #MARK: waitForState
           case "waitForState": {
-            return async (state: string | number, timeout?: number) =>
+            return async (state: string | number, timeout?: TOffset) =>
               await new Promise<ENTITY_STATE<ENTITY_ID>>(async done => {
                 const remove = () => {
-                  done = undefined;
                   listeners.delete(remove);
                   done = undefined;
                   logger.trace({ entity_id }, "remove [waitForState] listener");
@@ -326,8 +391,12 @@ export function ReferenceService({
 
                 event.on(entity_id, complete);
                 let wait: ReturnType<typeof sleep>;
-                if (is.number(timeout) && timeout > NONE) {
-                  wait = sleep(timeout);
+                if (is.undefined(timeout)) {
+                  return;
+                }
+                const duration = internal.utils.getIntervalMs(timeout);
+                if (duration > NONE) {
+                  wait = sleep(duration);
                   await wait;
                   wait = undefined;
                   if (done) {

package/src/testing/area.spec.mts

@@ -2,9 +2,9 @@ import { sleep } from "@digital-alchemy/core";
 import { subscribe } from "diagnostics_channel";
 
 import type { AreaDetails } from "../helpers/index.mts";
-import { AREA_REGISTRY_UPDATED } from "../helpers/index.mts";
+import { AREA_REGISTRY_UPDATED, ENTITY_REGISTRY_UPDATED } from "../helpers/index.mts";
 import { hassTestRunner, INTERNAL_MESSAGE } from "../mock_assistant/index.mts";
-import type { TAreaId } from "../user.mts";
+import type { ANY_ENTITY, TAreaId } from "../user.mts";
 
 const EXAMPLE_AREA = {
   area_id: "empty_area" as TAreaId,
@@ -200,4 +200,168 @@ describe("API", () => {
       });
     });
   });
+
+  describe("apply", () => {
+    it("should apply area to a single entity", async () => {
+      expect.assertions(2);
+      await hassTestRunner.run(({ lifecycle, hass, event }) => {
+        const spy = vi.spyOn(hass.socket, "sendMessage").mockImplementation(async () => undefined);
+        lifecycle.onReady(async () => {
+          const entity = "sensor.magic" as ANY_ENTITY;
+          const area = "living_room" as TAreaId;
+          const response = hass.area.apply(area, [entity]);
+          setImmediate(() => event.emit(ENTITY_REGISTRY_UPDATED));
+          const result = await response;
+
+          expect(spy).toHaveBeenCalledWith({
+            area_id: area,
+            entity_id: entity,
+            type: "config/entity_registry/update",
+          });
+          expect(result.updated).toEqual([entity]);
+        });
+      });
+    });
+
+    it("should apply area to multiple entities", async () => {
+      expect.assertions(3);
+      await hassTestRunner.run(({ lifecycle, hass, event }) => {
+        lifecycle.onReady(async () => {
+          const updateCalls: Array<{ area_id: TAreaId; entity_id: ANY_ENTITY; type: string }> = [];
+          vi.spyOn(hass.socket, "sendMessage").mockImplementation(async message => {
+            if (message?.type === "config/entity_registry/update") {
+              updateCalls.push(
+                message as { area_id: TAreaId; entity_id: ANY_ENTITY; type: string },
+              );
+              // Emit event asynchronously to ensure listener is registered
+              setImmediate(() => event.emit(ENTITY_REGISTRY_UPDATED));
+            }
+            return undefined;
+          });
+
+          const entities = ["sensor.magic", "light.kitchen_lamp"] as ANY_ENTITY[];
+          const area = "living_room" as TAreaId;
+          const result = await hass.area.apply(area, entities);
+
+          expect(updateCalls).toHaveLength(2);
+          expect(updateCalls).toEqual([
+            {
+              area_id: area,
+              entity_id: entities[0],
+              type: "config/entity_registry/update",
+            },
+            {
+              area_id: area,
+              entity_id: entities[1],
+              type: "config/entity_registry/update",
+            },
+          ]);
+          expect(result.updated).toEqual(entities);
+        });
+      });
+    });
+
+    it("should skip entities that already have the correct area", async () => {
+      expect.assertions(2);
+      await hassTestRunner.run(({ lifecycle, hass }) => {
+        lifecycle.onReady(async () => {
+          const spy = vi
+            .spyOn(hass.socket, "sendMessage")
+            .mockImplementation(async () => undefined);
+          // Find an entity that already has an area assigned
+          const entityWithArea = hass.entity.registry.current.find(item => item.area_id !== null);
+          if (!entityWithArea) {
+            throw new Error("No entity with area found in fixtures");
+          }
+
+          const entity = entityWithArea.entity_id as ANY_ENTITY;
+          const area = entityWithArea.area_id as TAreaId;
+          const result = await hass.area.apply(area, [entity]);
+
+          const updateCalls = spy.mock.calls.filter(
+            call => call[0]?.type === "config/entity_registry/update",
+          );
+          expect(updateCalls).toHaveLength(0);
+          expect(result.updated).toEqual([]);
+        });
+      });
+    });
+
+    it("should throw error for unknown entity", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ lifecycle, hass }) => {
+        lifecycle.onReady(async () => {
+          const unknownEntity = "sensor.unknown_entity" as ANY_ENTITY;
+          const area = "living_room" as TAreaId;
+
+          try {
+            await hass.area.apply(area, [unknownEntity]);
+          } catch (error) {
+            // InternalError structure: check various possible properties
+            const err = error as Record<string, unknown>;
+            const errorString = String(error);
+            const hasCode = err.code === "UNKNOWN_ENTITY";
+            const hasName = err.name === "UNKNOWN_ENTITY";
+            const hasMessage = String(err.message || "").includes("UNKNOWN_ENTITY");
+            const hasString = errorString.includes("UNKNOWN_ENTITY");
+            expect(hasCode || hasName || hasMessage || hasString).toBe(true);
+          }
+        });
+      });
+    });
+
+    it("should wait for ENTITY_REGISTRY_UPDATED before continuing", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ lifecycle, hass, event }) => {
+        vi.spyOn(hass.socket, "sendMessage").mockImplementation(async () => undefined);
+        lifecycle.onReady(async () => {
+          const entity = "sensor.magic" as ANY_ENTITY;
+          const area = "living_room" as TAreaId;
+          const response = hass.area.apply(area, [entity]);
+          let order = "";
+          setTimeout(() => {
+            order += "a";
+            event.emit(ENTITY_REGISTRY_UPDATED);
+          }, 5);
+          await response;
+          order += "b";
+          expect(order).toEqual("ab");
+        });
+      });
+    });
+
+    it("should return only updated entities when some are skipped", async () => {
+      expect.assertions(2);
+      await hassTestRunner.run(({ lifecycle, hass, event }) => {
+        lifecycle.onReady(async () => {
+          const spy = vi.spyOn(hass.socket, "sendMessage").mockImplementation(async message => {
+            if (message?.type === "config/entity_registry/update") {
+              setImmediate(() => event.emit(ENTITY_REGISTRY_UPDATED));
+            }
+            return undefined;
+          });
+
+          // Find an entity that already has "kitchen" area so it will be skipped
+          const entityWithArea = hass.entity.registry.current.find(
+            item => item.area_id === "kitchen",
+          );
+          if (!entityWithArea) {
+            throw new Error("No entity with kitchen area found in fixtures");
+          }
+
+          const existingEntity = entityWithArea.entity_id as ANY_ENTITY;
+          const newEntity = "sensor.magic" as ANY_ENTITY;
+          const newArea = "kitchen" as TAreaId;
+
+          const result = await hass.area.apply(newArea, [existingEntity, newEntity]);
+
+          const updateCalls = spy.mock.calls.filter(
+            call => call[0]?.type === "config/entity_registry/update",
+          );
+          expect(updateCalls).toHaveLength(1);
+          expect(result.updated).toEqual([newEntity]);
+        });
+      });
+    });
+  });
 });

package/src/testing/call-proxy.spec.mts

@@ -0,0 +1,241 @@
+import type { HassServiceDTO } from "../helpers/index.mts";
+import { hassTestRunner } from "../mock_assistant/index.mts";
+
+afterEach(async () => {
+  await hassTestRunner.teardown();
+  vi.restoreAllMocks();
+});
+
+describe("CallProxy", () => {
+  describe("pauseMessages", () => {
+    it("should return undefined when pauseMessages is true", async () => {
+      expect.assertions(2);
+      await hassTestRunner.run(({ lifecycle, hass }) => {
+        const spy = vi.spyOn(hass.socket, "sendMessage").mockImplementation(async () => undefined);
+        hass.socket.pauseMessages = true;
+
+        lifecycle.onReady(async () => {
+          const result = await hass.call.switch.turn_on({
+            entity_id: "switch.porch_light",
+          });
+
+          expect(result).toBeUndefined();
+          const callServiceCalls = spy.mock.calls.filter(
+            call =>
+              call[0]?.type === "call_service" &&
+              call[0]?.domain === "switch" &&
+              call[0]?.service === "turn_on",
+          );
+          expect(callServiceCalls).toHaveLength(0);
+        });
+      });
+    });
+
+    it("should call sendMessage when pauseMessages is false", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ lifecycle, hass }) => {
+        const spy = vi.spyOn(hass.socket, "sendMessage").mockImplementation(async () => undefined);
+        hass.socket.pauseMessages = false;
+
+        lifecycle.onReady(async () => {
+          await hass.call.switch.turn_on({
+            entity_id: "switch.porch_light",
+          });
+
+          expect(spy).toHaveBeenCalledWith(
+            expect.objectContaining({
+              domain: "switch",
+              service: "turn_on",
+              service_data: {
+                entity_id: "switch.porch_light",
+              },
+              type: "call_service",
+            }),
+            true,
+          );
+        });
+      });
+    });
+  });
+
+  describe("return_response", () => {
+    it("should include return_response in payload when service has response.optional", async () => {
+      expect.assertions(1);
+      const mockServices: HassServiceDTO[] = [
+        {
+          domain: "switch",
+          services: {
+            turn_on: {
+              description: "Test service",
+              fields: {},
+              name: "turn_on",
+              response: { optional: true },
+            },
+          },
+        },
+      ];
+
+      await hassTestRunner.run(({ lifecycle, hass, mock_assistant }) => {
+        mock_assistant.services.loadFixtures(mockServices);
+        vi.spyOn(hass.fetch, "listServices").mockImplementation(async () => mockServices);
+
+        const spy = vi
+          .spyOn(hass.socket, "sendMessage")
+          .mockImplementation(async () => ({ response: { success: true } }));
+
+        lifecycle.onReady(async () => {
+          await hass.call.switch.turn_on({ entity_id: "switch.bedroom_lamp" });
+
+          expect(spy).toHaveBeenCalledWith(
+            expect.objectContaining({
+              domain: "switch",
+              return_response: true,
+              service: "turn_on",
+              type: "call_service",
+            }),
+            true,
+          );
+        });
+      });
+    });
+
+    it("should return response when service returns a response", async () => {
+      expect.assertions(1);
+      const mockServices: HassServiceDTO[] = [
+        {
+          domain: "switch",
+          services: {
+            turn_on: {
+              description: "Test service",
+              fields: {},
+              name: "turn_on",
+              response: { optional: true },
+            },
+          },
+        },
+      ];
+
+      await hassTestRunner.run(({ lifecycle, hass, mock_assistant }) => {
+        mock_assistant.services.loadFixtures(mockServices);
+        vi.spyOn(hass.fetch, "listServices").mockImplementation(async () => mockServices);
+
+        const mockResponse = { data: "test_response" };
+        vi.spyOn(hass.socket, "sendMessage").mockImplementation(async () => ({
+          response: mockResponse,
+        }));
+
+        lifecycle.onReady(async () => {
+          const result = await hass.call.switch.turn_on({ entity_id: "switch.bedroom_lamp" });
+          expect(result).toEqual(mockResponse);
+        });
+      });
+    });
+
+    it("should return undefined when service does not return a response", async () => {
+      expect.assertions(1);
+      const mockServices: HassServiceDTO[] = [
+        {
+          domain: "switch",
+          services: {
+            turn_on: {
+              description: "Test service",
+              fields: {},
+              name: "turn_on",
+              response: { optional: true },
+            },
+          },
+        },
+      ];
+
+      await hassTestRunner.run(({ lifecycle, hass, mock_assistant }) => {
+        mock_assistant.services.loadFixtures(mockServices);
+        vi.spyOn(hass.fetch, "listServices").mockImplementation(async () => mockServices);
+
+        vi.spyOn(hass.socket, "sendMessage").mockImplementation(async () => ({}));
+
+        lifecycle.onReady(async () => {
+          const result = await hass.call.switch.turn_on({ entity_id: "switch.bedroom_lamp" });
+          expect(result).toBeUndefined();
+        });
+      });
+    });
+  });
+
+  describe("early access", () => {
+    it("should call console.trace when accessed before load with LOG_LEVEL trace", async () => {
+      expect.assertions(1);
+      const traceSpy = vi.spyOn(console, "trace").mockImplementation(() => {});
+
+      await hassTestRunner.configure({ boilerplate: { LOG_LEVEL: "trace" } }).run(({ hass }) => {
+        hass.call.switch;
+      });
+      expect(traceSpy).toHaveBeenCalledWith(`hass.call`);
+    });
+
+    it("should not log error when accessed before load with LOG_LEVEL not trace", async () => {
+      expect.assertions(2);
+      await hassTestRunner
+        .configure({ boilerplate: { LOG_LEVEL: "warn" } })
+        .run(({ lifecycle, hass, internal }) => {
+          const logger = internal.boilerplate.logger.getBaseLogger();
+          const errorSpy = vi.spyOn(logger, "error").mockImplementation(() => {});
+          const traceSpy = vi.spyOn(console, "trace").mockImplementation(() => {});
+
+          // Access hass.call in onPreInit, which runs before onBootstrap (where services load)
+          hass.call.switch;
+
+          lifecycle.onReady(() => {
+            expect(errorSpy).not.toHaveBeenCalled();
+            expect(traceSpy).not.toHaveBeenCalled();
+          });
+        });
+    });
+  });
+
+  describe("proxy methods", () => {
+    it("should return true for has when domain exists", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ lifecycle, hass }) => {
+        lifecycle.onReady(() => {
+          expect("switch" in hass.call).toBe(true);
+        });
+      });
+    });
+
+    it("should return false for has when domain does not exist", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ lifecycle, hass }) => {
+        lifecycle.onReady(() => {
+          expect("nonexistent_domain" in hass.call).toBe(false);
+        });
+      });
+    });
+
+    it("should return ownKeys with all domain keys", async () => {
+      expect.assertions(2);
+      await hassTestRunner.run(({ lifecycle, hass }) => {
+        lifecycle.onReady(() => {
+          const keys = Object.keys(hass.call);
+          expect(keys).toContain("switch");
+          expect(keys.length).toBeGreaterThan(0);
+        });
+      });
+    });
+
+    it("should return false when trying to set a property", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ lifecycle, hass }) => {
+        lifecycle.onReady(() => {
+          try {
+            // @ts-expect-error testing
+            hass.call.test_domain = {};
+          } catch {
+            // Some environments throw, others return false
+          }
+          // Verify the property was not set
+          expect("test_domain" in hass.call).toBe(false);
+        });
+      });
+    });
+  });
+});

package/src/testing/conversation.spec.mts

@@ -18,7 +18,7 @@ describe("Conversation Service", () => {
         },
       ];
 
-      await hassTestRunner.run(({ lifecycle, hass }) => {
+      await hassTestRunner.bootLibrariesFirst().run(({ lifecycle, hass }) => {
         const spy = vi
           .spyOn(hass.socket, "sendMessage")
           .mockImplementation(async () => ({ agents: mockAgents }));

package/src/testing/entity.spec.mts

@@ -242,8 +242,23 @@ describe("Entity", () => {
           const spy = vi.fn();
           subscribe(hass.diagnostics.entity.refresh_entities.name, spy);
 
+          // Mock getAllEntities to return entities so refresh doesn't call process.exit()
+          vi.spyOn(hass.fetch, "getAllEntities").mockResolvedValue([
+            {
+              attributes: {},
+              context: { id: "test", parent_id: null, user_id: null },
+              entity_id: "sensor.magic",
+              last_changed: dayjs(),
+              last_reported: dayjs(),
+              last_updated: dayjs(),
+              state: "unavailable",
+            } as ENTITY_STATE<ANY_ENTITY>,
+          ]);
+
           lifecycle.onReady(async () => {
             await hass.entity.refresh();
+            // Wait for setImmediate to complete
+            await sleep(10);
             expect(spy).toHaveBeenCalledWith(
               expect.objectContaining({
                 emitUpdates: [],

package/src/testing/id-by.spec.mts

@@ -137,6 +137,56 @@ describe("enabled entities", () => {
       });
     });
   });
+
+  describe("unique_id", () => {
+    it("find entity by unique_id without platform", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ lifecycle, hass }) => {
+        lifecycle.onReady(() => {
+          const entity = hass.idBy.unique_id(
+            "e1806fdc93296bbd5ab42967003cd38729ff9ba6cfeefc3e15a03ad01ac894fe",
+          );
+          expect(entity).toBe("sensor.magic");
+        });
+      });
+    });
+
+    it("find entity by unique_id with matching platform", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ lifecycle, hass }) => {
+        lifecycle.onReady(() => {
+          const entity = hass.idBy.unique_id(
+            "e1806fdc93296bbd5ab42967003cd38729ff9ba6cfeefc3e15a03ad01ac894fe",
+            "synapse",
+          );
+          expect(entity).toBe("sensor.magic");
+        });
+      });
+    });
+
+    it("find entity by unique_id with non-matching platform", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ lifecycle, hass }) => {
+        lifecycle.onReady(() => {
+          const entity = hass.idBy.unique_id(
+            "e1806fdc93296bbd5ab42967003cd38729ff9ba6cfeefc3e15a03ad01ac894fe",
+            "sun",
+          );
+          expect(entity).toBeUndefined();
+        });
+      });
+    });
+
+    it("find entity by unique_id with different platform", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ lifecycle, hass }) => {
+        lifecycle.onReady(() => {
+          const entity = hass.idBy.unique_id("5622d76001a335e3ea893c4d60d31b3d-next_dawn", "sun");
+          expect(entity).toBe("sensor.sun_next_dawn");
+        });
+      });
+    });
+  });
 });
 
 describe("disabled entities", () => {