@digital-alchemy/hass 24.10.1 → 24.11.1

package/src/extensions/reference.extension.ts

@@ -2,7 +2,7 @@ import { DOWN, is, NONE, sleep, TAnyFunction, TServiceParams, UP } from "@digita
 import dayjs, { Dayjs } from "dayjs";
 import { Get } from "type-fest";
 
-import { SERVICE_LIST_UPDATED } from "..";
+import { SERVICE_LIST_UPDATED, SOCKET_CONNECTED } from "..";
 import {
   TAreaId,
   TDeviceId,
@@ -26,15 +26,65 @@ import {
   PICK_FROM_FLOOR,
   PICK_FROM_LABEL,
   PICK_FROM_PLATFORM,
+  RemoveCallback,
 } from "../helpers";
 
-export function ReferenceExtension({
+/**
+ * ## Overview
+ *
+ * This service is intended for the creation of type safe entity references based on entity id.
+ *
+ * ```typescript
+ * const ref = hass.refBy.id("switch.example");
+ * ```
+ *
+ * These contain specialized type definitions that gets looked up by entity id, making typescript report info about the desired entity.
+ *
+ * ## Capabilities
+ *
+ * ### Event Listeners
+ *
+ * Run a callback in response to
+ * - `.onUpdate((new_state, old_state) => ...)`
+ * - `.once((new_state, old_state) => ...)`
+ *
+ * ### State lookups
+ *
+ * - `.nextState(timeout?)`
+ * - `.waitForState(state, timeout?)`
+ * - `.previous.state` | `.previous.attributes`
+ *
+ * ### Service Calling
+ *
+ * For services that appear on the same domain as the provided entity, the service call can be made directly from the reference.
+ *
+ * >  Ex: `switch.example` calling `switch.turn_on`
+ *
+ * ```typescript
+ * ref.turn_on();
+ * ```
+ *
+ * The `entity_id` property that would normally be required is automatically provided by the proxy.
+ *
+ * ### Property Lookups
+ *
+ * - `.state`
+ * - `.entity_id`
+ * - `.attributes`
+ *
+ * ## Garbage Collection
+ *
+ * - `.removeAllListeners()`
+ *
+ * The reference may call the remove all active event listeners and timers at any time.
+ * It will interrupt any timers (nextState/waitForState), as well as detach any event listeners
+ */
+export function ReferenceService({
   hass,
   logger,
   internal,
   event,
 }: TServiceParams): HassReferenceService {
-  const ENTITY_PROXIES = new Map<ANY_ENTITY, ByIdProxy<ANY_ENTITY>>();
   // #MARK:proxyGetLogic
   function proxyGetLogic<ENTITY extends ANY_ENTITY = ANY_ENTITY, PROPERTY extends string = string>(
     entity: ENTITY,
@@ -64,238 +114,307 @@ export function ReferenceExtension({
   }
 
   // #MARK: byId
+  // ! Calls to this function MUST ALWAYS go through `hass.refBy.id`
+  // never call this function directly 💧
   function byId<ENTITY_ID extends ANY_ENTITY>(entity_id: ENTITY_ID): ByIdProxy<ENTITY_ID> {
     const entity_domain = domain(entity_id) as ALL_SERVICE_DOMAINS;
-    if (!ENTITY_PROXIES.has(entity_id)) {
-      const { ...thing } = hass.entity.getCurrentState(entity_id) as ByIdProxy<ENTITY_ID>;
-      let loaded = false;
-
-      function keys() {
-        const entityDomain = domain(entity_id);
-        return [
-          "attributes",
-          "entity_id",
-          "history",
-          "last",
-          "nextState",
-          "once",
-          "onUpdate",
-          "previous",
-          "removeAllListeners",
-          "state",
-          "waitForState",
-          ...hass.configure
-            .getServices()
-            .filter(({ domain }) => domain === entityDomain)
-            .flatMap(i => Object.keys(i.services))
-            .sort((a, b) => (a > b ? UP : DOWN)),
-        ];
+    const { ...thing } = hass.entity.getCurrentState(entity_id) as ByIdProxy<ENTITY_ID>;
+    let loaded = false;
+
+    function keys() {
+      const entityDomain = domain(entity_id);
+      return [
+        "attributes",
+        "entity_id",
+        "history",
+        "last",
+        "nextState",
+        "once",
+        "onUpdate",
+        "previous",
+        "removeAllListeners",
+        "state",
+        "waitForState",
+        ...hass.configure
+          .getServices()
+          .filter(({ domain }) => domain === entityDomain)
+          .flatMap(i => Object.keys(i.services))
+          .sort((a, b) => (a > b ? UP : DOWN)),
+      ];
+    }
+
+    function appendKeys(force = false) {
+      if (loaded && !force) {
+        return;
       }
-      function appendKeys(force = false) {
-        if (loaded && !force) {
-          return;
-        }
-        // Not gonna build types for this, and ts-expect-error fails in jest
-        // This is a weird hack for an obscure feature, so sue me
-        //
-        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-        // @ts-ignore
-        keys().forEach(i => (thing[i] ??= () => {}));
-        if (!is.empty(hass.configure.getServices())) {
-          loaded = true;
-        }
+      // Not gonna build types for this, and ts-expect-error fails in jest
+      // This is a weird hack for an obscure feature, so sue me
+      //
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore
+      keys().forEach(i => (thing[i] ??= () => {}));
+      if (!is.empty(hass.configure.getServices())) {
+        loaded = true;
       }
-      event.on(SERVICE_LIST_UPDATED, () => appendKeys(true));
-      ENTITY_PROXIES.set(
-        entity_id,
-        // just because you can't do generics properly....
-        new Proxy(thing, {
-          // things that shouldn't be needed: this extract
-          // eslint-disable-next-line sonarjs/function-return-type
-          get: (_, property: Extract<keyof ByIdProxy<ENTITY_ID>, string>) => {
-            switch (property) {
-              // * onUpdate
-              case "onUpdate": {
-                return (callback: TAnyFunction) => {
-                  const removableCallback = async (
-                    a: ENTITY_STATE<ENTITY_ID>,
-                    b: ENTITY_STATE<ENTITY_ID>,
-                  ) => await internal.safeExec(async () => callback(a, b, remove));
-                  function remove() {
-                    event.removeListener(entity_id, removableCallback);
-                  }
+    }
 
-                  event.on(entity_id, removableCallback);
-                  return { remove };
-                };
-              }
+    event.on(SERVICE_LIST_UPDATED, () => appendKeys(true));
+    const listeners = new Set<() => void>();
 
-              // * removeAllListeners
-              case "removeAllListeners": {
-                return function () {
-                  event.removeAllListeners(entity_id);
-                };
+    // just because you can't do generics properly....
+    return new Proxy(thing, {
+      // things that shouldn't be needed: this extract
+      // eslint-disable-next-line sonarjs/function-return-type
+      get: (_, property: Extract<keyof ByIdProxy<ENTITY_ID>, string>) => {
+        switch (property) {
+          // #MARK: onUpdate
+          case "onUpdate": {
+            return (callback: TAnyFunction) => {
+              const removableCallback = async (
+                new_state: ENTITY_STATE<ENTITY_ID>,
+                old_state: ENTITY_STATE<ENTITY_ID>,
+              ) => await internal.safeExec(async () => callback(new_state, old_state, remove));
+              function remove() {
+                event.removeListener(entity_id, removableCallback);
+                event.removeListener(SOCKET_CONNECTED, removableCallback);
+                listeners.delete(remove);
+                logger.trace({ entity_id }, "remove [onUpdate] listener");
               }
 
-              // * history
-              case "history": {
-                return async function (from: Dayjs | Date, to: Dayjs | Date) {
-                  return await hass.fetch.fetchEntityHistory(entity_id, from, to);
-                };
-              }
+              event.on(entity_id, removableCallback);
+              event.on(SOCKET_CONNECTED, removableCallback);
+              listeners.add(remove);
 
-              // * once
-              case "once": {
-                return (callback: TAnyFunction) =>
-                  event.once(entity_id, async (a, b) => callback(a, b));
-              }
+              return is.removeFn(remove);
+            };
+          }
 
-              // * entity_id
-              case "entity_id": {
-                return entity_id;
-              }
+          // #MARK: addListener
+          case "addListener": {
+            return function (remove: RemoveCallback) {
+              listeners.add(remove);
+            };
+          }
 
-              // * previous
-              case "previous": {
-                return hass.entity.previousState(entity_id);
-              }
+          // #MARK: removeAllListeners
+          case "removeAllListeners": {
+            return function () {
+              // remove will delete from set
+              listeners.forEach(remove => remove());
+            };
+          }
 
-              // * nextState
-              case "nextState": {
-                return async (timeout?: number) =>
-                  await new Promise<ENTITY_STATE<ENTITY_ID>>(async done => {
-                    const complete = (entity: ENTITY_STATE<ENTITY_ID>) => {
-                      if (done) {
-                        done(entity satisfies ENTITY_STATE<ENTITY_ID>);
-                        done = undefined;
-                      }
-                    };
-                    event.once(entity_id, complete);
-                    if (is.number(timeout) && timeout > NONE) {
-                      await sleep(timeout);
-                      if (done) {
-                        logger.debug({ entity_id, name: "nextState", timeout }, "timed out");
-                        done(undefined);
-                        done = undefined;
-                        event.removeListener(entity_id, complete);
-                      }
-                    }
-                  });
-              }
+          // #MARK: history
+          case "history": {
+            return async function (from: Dayjs | Date, to: Dayjs | Date) {
+              return await hass.fetch.fetchEntityHistory(entity_id, from, to);
+            };
+          }
 
-              // * waitForState
-              case "waitForState": {
-                return async (state: string | number, timeout?: number) =>
-                  await new Promise<ENTITY_STATE<ENTITY_ID>>(async done => {
-                    const complete = (entity: ENTITY_STATE<ENTITY_ID>) => {
-                      if (entity.state !== state) {
-                        logger.trace(
-                          {
-                            expected: state,
-                            incoming: entity.state,
-                            name: "waitForState",
-                          },
-                          `state did not match`,
-                        );
-                        return;
-                      }
-                      if (done) {
-                        done(entity satisfies ENTITY_STATE<ENTITY_ID>);
-                        done = undefined;
-                        event.removeListener(entity_id, complete);
-                      }
-                    };
-                    event.on(entity_id, complete);
-                    if (is.number(timeout) && timeout > NONE) {
-                      await sleep(timeout);
-                      if (done) {
-                        logger.debug({ entity_id, name: "waitForState", timeout }, "timed out");
-                        done(undefined);
-                        done = undefined;
-                        event.removeListener(entity_id, complete);
-                      }
-                    }
-                  });
-              }
-            }
-            if (hass.configure.isService(entity_domain, property)) {
-              return async function (data = {}) {
-                // @ts-expect-error it's fine
-                return await hass.call[entity_domain][property]({
-                  entity_id,
-                  ...data,
-                });
+          // #MARK: once
+          case "once": {
+            return (callback: TAnyFunction) => {
+              const remove = () => {
+                event.removeListener(entity_id, wrapped);
+                listeners.delete(remove);
+                logger.trace({ entity_id }, "remove [once] listener");
+              };
+              const wrapped = async (a: ENTITY_STATE<ENTITY_ID>, b: ENTITY_STATE<ENTITY_ID>) => {
+                listeners.delete(remove);
+                callback(a, b);
               };
-            }
-            return proxyGetLogic(entity_id, property);
-          },
-          has(_, property: string) {
-            appendKeys();
-            return property in thing;
-          },
-          ownKeys() {
-            appendKeys();
-            return Object.keys(thing);
-          },
-          set(_, property: Extract<keyof ByIdProxy<ENTITY_ID>, string>, value: unknown) {
-            // * state
-            if (property === "state") {
-              setImmediate(async () => {
-                logger.debug({ entity_id, state: value }, `emitting set state via rest`);
-                await hass.fetch.updateEntity(entity_id, {
-                  state: value as string | number,
-                });
+              listeners.add(remove);
+              event.once(entity_id, wrapped);
+              return is.removeFn(remove);
+            };
+          }
+
+          // #MARK: entity_id
+          case "entity_id": {
+            return entity_id;
+          }
+
+          // #MARK: previous
+          case "previous": {
+            return hass.entity.previousState(entity_id);
+          }
+
+          // #MARK: nextState
+          case "nextState": {
+            return async (timeout?: number) =>
+              await new Promise<ENTITY_STATE<ENTITY_ID>>(async done => {
+                // - set up cleanup function
+                const remove = () => {
+                  listeners.delete(remove);
+                  event.removeListener(entity_id, complete);
+                  done = undefined;
+                  logger.trace({ entity_id }, "remove [nextState] listener");
+                  if (wait) {
+                    logger.trace({ entity_id }, "stopping [nextState] race timer");
+                    wait.kill("stop");
+                  }
+                };
+                listeners.add(remove);
+
+                // - add wrapper & make friendly with race
+                const complete = (entity: ENTITY_STATE<ENTITY_ID>) => {
+                  if (done) {
+                    done(entity satisfies ENTITY_STATE<ENTITY_ID>);
+                    done = undefined;
+                  }
+                };
+
+                // - attach single run listener
+                event.once(entity_id, complete);
+
+                // - race!
+                let wait: ReturnType<typeof sleep>;
+                if (is.number(timeout) && timeout > NONE) {
+                  // keep track of sleep so it can be cleaned up also
+                  wait = sleep(timeout);
+                  await wait;
+                  wait = undefined;
+                  if (done) {
+                    logger.debug({ entity_id, name: "nextState", timeout }, "timed out");
+                    done(undefined);
+                    remove();
+                  }
+                }
               });
-              return true;
-            }
-            // * attributes
-            if (property === "attributes") {
-              if (!is.object(value)) {
-                logger.error(`can only provide objects as attributes`);
-                return false;
-              }
-              setImmediate(async () => {
-                logger.debug(
-                  { attributes: Object.keys(value), entity_id },
-                  `updating attributes via rest`,
-                );
-                await hass.fetch.updateEntity(entity_id, {
-                  attributes: value,
-                });
+          }
+
+          // #MARK: waitForState
+          case "waitForState": {
+            return async (state: string | number, timeout?: number) =>
+              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");
+                  if (wait) {
+                    logger.trace({ entity_id }, "stopping [waitForState] race timer");
+
+                    wait.kill("stop");
+                  }
+                  event.removeListener(entity_id, complete);
+                };
+                listeners.add(remove);
+
+                const complete = (entity: ENTITY_STATE<ENTITY_ID>) => {
+                  if (entity.state !== state) {
+                    logger.trace(
+                      {
+                        expected: state,
+                        incoming: entity.state,
+                        name: "waitForState",
+                      },
+                      `state did not match`,
+                    );
+                    return;
+                  }
+                  if (done) {
+                    done(entity satisfies ENTITY_STATE<ENTITY_ID>);
+                    remove();
+                  }
+                };
+
+                event.on(entity_id, complete);
+                let wait: ReturnType<typeof sleep>;
+                if (is.number(timeout) && timeout > NONE) {
+                  wait = sleep(timeout);
+                  await wait;
+                  wait = undefined;
+                  if (done) {
+                    logger.debug({ entity_id, name: "waitForState", timeout }, "timed out");
+                    done(undefined);
+                    remove();
+                  }
+                }
               });
-              return true;
-            }
-            logger.error({ entity_id, property }, `cannot set property on entity`);
+          }
+        }
+        // #MARK: service calls
+        if (hass.configure.isService(entity_domain, property)) {
+          return async function (data = {}) {
+            // @ts-expect-error it's fine
+            return await hass.call[entity_domain][property]({
+              entity_id,
+              ...data,
+            });
+          };
+        }
+        return proxyGetLogic(entity_id, property);
+      },
+      // #MARK: has
+      has(_, property: string) {
+        appendKeys();
+        return property in thing;
+      },
+      // #MARK: ownKeys
+      ownKeys() {
+        appendKeys();
+        return Object.keys(thing);
+      },
+      // #MARK: set
+      set(_, property: Extract<keyof ByIdProxy<ENTITY_ID>, string>, value: unknown) {
+        // * state
+        if (property === "state") {
+          setImmediate(async () => {
+            logger.debug({ entity_id, state: value }, `emitting set state via rest`);
+            await hass.fetch.updateEntity(entity_id, {
+              state: value as string | number,
+            });
+          });
+          return true;
+        }
+        // * attributes
+        if (property === "attributes") {
+          if (!is.object(value)) {
+            logger.error(`can only provide objects as attributes`);
             return false;
-          },
-        }),
-      );
-    }
-    return ENTITY_PROXIES.get(entity_id) as ByIdProxy<ENTITY_ID>;
+          }
+          setImmediate(async () => {
+            logger.debug(
+              { attributes: Object.keys(value), entity_id },
+              `updating attributes via rest`,
+            );
+            await hass.fetch.updateEntity(entity_id, {
+              attributes: value,
+            });
+          });
+          return true;
+        }
+        logger.error({ entity_id, property }, `cannot set property on entity`);
+        return false;
+      },
+    });
   }
 
+  // #MARK: <return>
   return {
     area: <AREA extends TAreaId, DOMAINS extends TRawDomains = TRawDomains>(
       area: AREA,
       ...domains: DOMAINS[]
     ): ByIdProxy<PICK_FROM_AREA<AREA, DOMAINS>>[] =>
-      hass.idBy.area<AREA, DOMAINS>(area, ...domains).map(id => byId(id)),
+      hass.idBy.area<AREA, DOMAINS>(area, ...domains).map(id => hass.refBy.id(id)),
 
     device: <DEVICE extends TDeviceId, DOMAINS extends TRawDomains = TRawDomains>(
       device: DEVICE,
       ...domains: DOMAINS[]
     ): ByIdProxy<PICK_FROM_DEVICE<DEVICE, DOMAINS>>[] =>
-      hass.idBy.device<DEVICE, DOMAINS>(device, ...domains).map(id => byId(id)),
+      hass.idBy.device<DEVICE, DOMAINS>(device, ...domains).map(id => hass.refBy.id(id)),
 
     domain: <DOMAIN extends TRawDomains = TRawDomains>(
       domain: DOMAIN,
-    ): ByIdProxy<PICK_ENTITY<DOMAIN>>[] => hass.idBy.domain<DOMAIN>(domain).map(id => byId(id)),
+    ): ByIdProxy<PICK_ENTITY<DOMAIN>>[] =>
+      hass.idBy.domain<DOMAIN>(domain).map(id => hass.refBy.id(id)),
 
     floor: <FLOOR extends TFloorId, DOMAINS extends TRawDomains = TRawDomains>(
       floor: FLOOR,
       ...domains: DOMAINS[]
     ): ByIdProxy<PICK_FROM_FLOOR<FLOOR, DOMAINS>>[] =>
-      hass.idBy.floor<FLOOR, DOMAINS>(floor, ...domains).map(id => byId(id)),
+      hass.idBy.floor<FLOOR, DOMAINS>(floor, ...domains).map(id => hass.refBy.id(id)),
 
     id: byId,
 
@@ -303,13 +422,13 @@ export function ReferenceExtension({
       label: LABEL,
       ...domains: DOMAINS[]
     ): ByIdProxy<PICK_FROM_LABEL<LABEL, DOMAINS>>[] =>
-      hass.idBy.label<LABEL, DOMAINS>(label, ...domains).map(id => byId(id)),
+      hass.idBy.label<LABEL, DOMAINS>(label, ...domains).map(id => hass.refBy.id(id)),
 
     platform: <PLATFORM extends TPlatformId, DOMAINS extends TRawDomains = TRawDomains>(
       platform: PLATFORM,
       ...domains: DOMAINS[]
     ): ByIdProxy<PICK_FROM_PLATFORM<PLATFORM, DOMAINS>>[] =>
-      hass.idBy.platform<PLATFORM, DOMAINS>(platform, ...domains).map(id => byId(id)),
+      hass.idBy.platform<PLATFORM, DOMAINS>(platform, ...domains).map(id => hass.refBy.id(id)),
 
     unique_id: <
       UNIQUE_ID extends TUniqueId,
@@ -322,9 +441,12 @@ export function ReferenceExtension({
     ): ByIdProxy<ENTITY_ID> => {
       const id = hass.idBy.unique_id<UNIQUE_ID, ENTITY_ID>(unique_id);
       if (!id) {
+        // mental note:
+        // this is technically fixable, but would require emitting internal events
+        // for both entity_id & unique_id
         return undefined;
       }
-      return byId(id);
+      return hass.refBy.id(id);
     },
   };
 }

package/src/extensions/websocket-api.extension.ts

@@ -493,10 +493,10 @@ export function WebsocketAPI({
     } else {
       socketEvents.on(event, callback);
     }
-    return () => {
+    return is.removeFn(() => {
       logger.trace({ context, event, name: onEvent }, `removing socket event listener`);
       socketEvents.removeListener(event, callback);
-    };
+    });
   }
 
   // #MARK: subscribe
@@ -506,7 +506,7 @@ export function WebsocketAPI({
     exec,
   }: SocketSubscribeOptions<EVENT>) {
     await hass.socket.sendMessage({ event_type, type: "subscribe_events" });
-    hass.socket.onEvent({
+    return hass.socket.onEvent({
       context,
       event: event_type,
       exec,
@@ -527,6 +527,7 @@ export function WebsocketAPI({
       // attach anyways, for restarts or whatever
     }
     event.on(SOCKET_CONNECTED, wrapped);
+    return is.removeFn(() => event.removeListener(SOCKET_CONNECTED, wrapped));
   }
 
   // #MARK: return object

package/src/hass.module.ts

@@ -7,13 +7,13 @@ import {
   Configure,
   Device,
   EntityManager,
-  Events,
+  EventsService,
   FetchAPI,
   FetchInternals,
   Floor,
   IDByExtension,
   Label,
-  ReferenceExtension,
+  ReferenceService,
   Registry,
   WebsocketAPI,
   Zone,
@@ -158,7 +158,7 @@ export const LIB_HASS = CreateLibrary({
     /**
      * named event attachments
      */
-    events: Events,
+    events: EventsService,
 
     /**
      * rest api commands
@@ -188,7 +188,7 @@ export const LIB_HASS = CreateLibrary({
     /**
      * obtain references to entities
      */
-    refBy: ReferenceExtension,
+    refBy: ReferenceService,
 
     /**
      * interact with the home assistant registry