@digital-alchemy/hass 25.11.16 → 25.11.17-beta.0

package/package.json

@@ -3,7 +3,7 @@
   "name": "@digital-alchemy/hass",
   "repository": "https://github.com/Digital-Alchemy-TS/hass",
   "homepage": "https://docs.digital-alchemy.app",
-  "version": "25.11.16",
+  "version": "25.11.17-beta.0",
   "description": "Typescript APIs for Home Assistant. Includes rest & websocket bindings",
   "scripts": {
     "build": "rm -rf dist/; tsc",
@@ -58,25 +58,25 @@
   },
   "license": "MIT",
   "devDependencies": {
-    "@cspell/eslint-plugin": "^9.2.2",
-    "@digital-alchemy/core": "^25.10.26",
+    "@cspell/eslint-plugin": "^9.3.2",
+    "@digital-alchemy/core": "^25.11.19",
     "@digital-alchemy/synapse": "^25.8.21",
-    "@digital-alchemy/type-writer": "^25.10.12",
-    "@eslint/compat": "^1.4.0",
+    "@digital-alchemy/type-writer": "^25.11.16",
+    "@eslint/compat": "^2.0.0",
     "@eslint/eslintrc": "^3.3.1",
-    "@eslint/js": "^9.38.0",
+    "@eslint/js": "^9.39.1",
     "@faker-js/faker": "^10.1.0",
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "^24.9.1",
+    "@types/node": "^24.10.1",
     "@types/node-cron": "^3.0.11",
     "@types/semver": "^7.7.1",
     "@types/ws": "^8.18.1",
-    "@typescript-eslint/eslint-plugin": "8.46.2",
-    "@typescript-eslint/parser": "8.46.2",
-    "@vitest/coverage-v8": "^4.0.3",
-    "dayjs": "^1.11.18",
+    "@typescript-eslint/eslint-plugin": "8.46.4",
+    "@typescript-eslint/parser": "8.46.4",
+    "@vitest/coverage-v8": "^4.0.10",
+    "dayjs": "^1.11.19",
     "dotenv": "^17.2.3",
-    "eslint": "9.38.0",
+    "eslint": "9.39.1",
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-jsonc": "^2.21.0",
@@ -93,18 +93,18 @@
     "tsx": "^4.20.6",
     "typescript": "^5.9.3",
     "uuid": "^13.0.0",
-    "vitest": "^4.0.3",
+    "vitest": "^4.0.10",
     "ws": "^8.18.3"
   },
   "peerDependencies": {
     "@digital-alchemy/core": "*"
   },
   "dependencies": {
-    "dayjs": "^1.11.18",
+    "dayjs": "^1.11.19",
     "semver": "^7.7.3",
-    "type-fest": "^5.1.0",
+    "type-fest": "^5.2.0",
     "uuid": "^13.0.0",
     "ws": "^8.18.3"
   },
-  "packageManager": "yarn@4.10.3"
+  "packageManager": "yarn@4.11.0"
 }

package/src/helpers/entity-state.mts

@@ -1,4 +1,4 @@
-import type { FIRST, RemoveCallback, TBlackHole } from "@digital-alchemy/core";
+import type { FIRST, RemoveCallback, TBlackHole, TContext, TOffset } from "@digital-alchemy/core";
 import type { Dayjs } from "dayjs";
 import type { Except } from "type-fest";
 
@@ -46,6 +46,17 @@ export type RemovableCallback<ENTITY_ID extends ANY_ENTITY> = (
   callback: TEntityUpdateCallback<ENTITY_ID>,
 ) => RemoveCallback;
 
+export type OnStateForOptions<ENTITY_ID extends ANY_ENTITY> = (
+  | (Pick<ENTITY_STATE<ENTITY_ID>, "state"> & { matches?: never })
+  | ({
+      matches: (new_state: ENTITY_STATE<ENTITY_ID>, old_state: ENTITY_STATE<ENTITY_ID>) => boolean;
+    } & { state?: never })
+) & {
+  for: TOffset;
+  context?: TContext;
+  exec: (state: ByIdProxy<ENTITY_ID>) => TBlackHole;
+};
+
 export type ByIdProxy<ENTITY_ID extends ANY_ENTITY> = ENTITY_STATE<ENTITY_ID> & {
   entity_id: ENTITY_ID;
   /**
@@ -63,11 +74,17 @@ export type ByIdProxy<ENTITY_ID extends ANY_ENTITY> = ENTITY_STATE<ENTITY_ID> &
   /**
    * Will resolve with the next state of the next value. No time limit
    */
-  nextState: (timeoutMs?: number) => Promise<ENTITY_STATE<ENTITY_ID>>;
+  nextState: (timeout?: TOffset) => Promise<ENTITY_STATE<ENTITY_ID>>;
+  /**
+   * Runs on state change -
+   * If state matches the indicated target, then a timer will be initiated
+   * As long as the condition holds true, the callback will be executed at end of the timer
+   */
+  onStateFor: (options: OnStateForOptions<ENTITY_ID>) => RemoveCallback;
   /**
    * Will resolve when state
    */
-  waitForState: (state: string | number, timeoutMs?: number) => Promise<ENTITY_STATE<ENTITY_ID>>;
+  waitForState: (state: string | number, timeout?: TOffset) => Promise<ENTITY_STATE<ENTITY_ID>>;
   /**
    * Access the immediate previous entity state
    */

package/src/helpers/utility.mts

@@ -1,6 +1,6 @@
 import type { TBlackHole } from "@digital-alchemy/core";
 import { is } from "@digital-alchemy/core";
-import type { Dayjs } from "dayjs";
+import { type Dayjs } from "dayjs";
 import type { Get } from "type-fest";
 
 import type {

package/src/mock_assistant/mock-assistant.module.mts

@@ -17,7 +17,6 @@ import {
   MockWebsocketAPI,
   MockZoneExtension,
 } from "./services/index.mts";
-
 export const LIB_MOCK_ASSISTANT = CreateLibrary({
   configuration: {
     EMIT_SLEEP: {

package/src/mock_assistant/services/websocket-api.service.mts

@@ -5,6 +5,7 @@ import type { PartialDeep, WritableDeep } from "type-fest";
 import type WS from "ws";
 
 import type { SocketMessageDTO } from "../../helpers/index.mts";
+import { SOCKET_CONNECTED } from "../../services/websocket-api.service.mts";
 
 const CONNECTION_CLOSED = 0;
 // const CONNECTION_OPEN = 1;
@@ -13,7 +14,7 @@ const UNLIMITED = 0;
 
 export const INTERNAL_MESSAGE = "INTERNAL_MESSAGE";
 
-export function MockWebsocketAPI({ hass, config, lifecycle }: TServiceParams) {
+export function MockWebsocketAPI({ hass, config, lifecycle, event }: TServiceParams) {
   const connection = new EventEmitter() as WritableDeep<WS>;
   connection.setMaxListeners(UNLIMITED);
   lifecycle.onShutdownStart(() => {
@@ -28,7 +29,8 @@ export function MockWebsocketAPI({ hass, config, lifecycle }: TServiceParams) {
   // connection.send = (...data) =>
 
   hass.socket.createConnection = () => {
-    setImmediate(() => {
+    // Use Promise.resolve().then() instead of setImmediate for better compatibility with fake timers
+    Promise.resolve().then(() => {
       if (!config.mock_assistant.PASS_AUTH) {
         return;
       }
@@ -37,6 +39,40 @@ export function MockWebsocketAPI({ hass, config, lifecycle }: TServiceParams) {
     return connection;
   };
 
+  // Mock init - resolves immediately for tests
+  // The real service's init() waits for onSocketReady, but in tests we don't need that
+  async function init(): Promise<void> {
+    if (hass.socket.connection) {
+      return;
+    }
+    hass.socket.connection = hass.socket.createConnection("");
+    hass.socket.setConnectionState("connecting");
+
+    // Set up message handler - the real service's handlers registered in onPreInit
+    // will process messages via registerMessageHandler
+    connection.on("message", async (message: string) => {
+      try {
+        JSON.parse(message.toString());
+        // Real service's handlers will process this via onMessage/registerMessageHandler
+      } catch {
+        // Ignore parse errors
+      }
+    });
+
+    // In tests, we can resolve immediately without waiting for real socket handshake
+    // The real service's onBootstrap calls this, and it needs to complete for lifecycle to progress
+    hass.socket.setConnectionState("connected");
+
+    // Emit auth_ok to trigger the real service's handlers (registered in onPreInit)
+    // This allows the real service's auth_ok handler to run and do its setup
+    if (config.mock_assistant.PASS_AUTH) {
+      // Use microtask to ensure handlers are registered first
+      await Promise.resolve();
+      sendMessage({ type: "auth_ok" });
+      event.emit(SOCKET_CONNECTED);
+    }
+  }
+
   connection.send = (data: string) => {
     const payload = JSON.parse(data) as { type: string; id: number };
     connection.emit(INTERNAL_MESSAGE, payload);
@@ -49,7 +85,7 @@ export function MockWebsocketAPI({ hass, config, lifecycle }: TServiceParams) {
         return;
       }
       default: {
-        setImmediate(() => {
+        Promise.resolve().then(() => {
           sendMessage({
             id: payload.id,
             result: null,
@@ -61,13 +97,19 @@ export function MockWebsocketAPI({ hass, config, lifecycle }: TServiceParams) {
   };
 
   function sendMessage(data: PartialDeep<SocketMessageDTO>) {
-    setImmediate(() => {
+    // Use Promise.resolve() instead of setImmediate for better fake timer compatibility
+    Promise.resolve().then(() => {
       connection.emit("message", JSON.stringify(data));
     });
   }
 
   return {
+    attachScheduledFunctions: () => {
+      // Mock implementation - no-op for tests
+      // The real websocket service sets up intervals here, but we don't need them in tests
+    },
     connection: connection as WS,
+    init,
     onMessage<DATA extends object>(
       type: string,
       callback: (data: DATA & MessageData) => TBlackHole,

package/src/services/feature.service.mts

@@ -38,7 +38,9 @@ export function HassFeatureService({
     }, 0);
   }
 
-  function lookup(input: PICK_ENTITY | ByIdProxy<PICK_ENTITY>) {
+  function lookup<T extends UsedSupportedFeatureDomains>(
+    input: PICK_ENTITY | ByIdProxy<PICK_ENTITY<T>>,
+  ) {
     const ref = is.string(input) ? hass.refBy.id(input) : input;
     const attributes = ref.attributes as { supported_features: number };
     return attributes?.supported_features ?? 0;
@@ -69,7 +71,9 @@ export function HassFeatureService({
    * Helper function to get all supported features as an array
    * Can accept a number (bitmask), entity ID, or entity proxy
    */
-  function getSupportedFeatures(input: number | PICK_ENTITY | ByIdProxy<PICK_ENTITY>): number[] {
+  function getSupportedFeatures<T extends UsedSupportedFeatureDomains>(
+    input: number | PICK_ENTITY | ByIdProxy<PICK_ENTITY<T>>,
+  ): number[] {
     const features = is.number(input) ? input : lookup(input);
 
     const supported: number[] = [];
@@ -84,10 +88,9 @@ export function HassFeatureService({
   }
 
   function listEntityFeatures<
-    DOMAIN extends UsedSupportedFeatureDomains = UsedSupportedFeatureDomains,
-  >(
-    input: PICK_ENTITY<DOMAIN> | ByIdProxy<PICK_ENTITY<DOMAIN>>,
-  ): SupportedEntityFeatures<DOMAIN>[] {
+    DOMAIN extends UsedSupportedFeatureDomains,
+    ENTITY extends PICK_ENTITY<DOMAIN> = PICK_ENTITY<DOMAIN>,
+  >(input: ENTITY | ByIdProxy<ENTITY>): SupportedEntityFeatures<DOMAIN>[] {
     const inputDomain = domain(is.string(input) ? input : input.entity_id);
     const domainFeatures = SUPPORTED_FEATURES[inputDomain.toUpperCase() as SupportedFeatureDomains];
     if (!domainFeatures) {

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`);
@@ -134,6 +139,7 @@ export function ReferenceService({
         "last",
         "nextState",
         "once",
+        "onStateFor",
         "onUpdate",
         "previous",
         "removeAllListeners",
@@ -170,8 +176,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 +306,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 +334,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,7 +354,7 @@ 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;
@@ -326,8 +390,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/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: [],