@digital-alchemy/hass 24.9.3 → 24.9.5

package/src/extensions/id-by.extension.ts

@@ -0,0 +1,157 @@
+import { is, TServiceParams } from "@digital-alchemy/core";
+
+import {
+  TAreaId,
+  TDeviceId,
+  TFloorId,
+  TLabelId,
+  TPlatformId,
+  TUniqueId,
+  TUniqueIDMapping,
+} from "../dynamic";
+import {
+  ALL_DOMAINS,
+  ANY_ENTITY,
+  EntityRegistryItem,
+  IDByInterface,
+  PICK_ENTITY,
+  PICK_FROM_AREA,
+  PICK_FROM_DEVICE,
+  PICK_FROM_FLOOR,
+  PICK_FROM_LABEL,
+  PICK_FROM_PLATFORM,
+} from "../helpers";
+
+const check = <RAW extends ANY_ENTITY>(raw: RAW[], domains: ALL_DOMAINS[]) => {
+  if (!is.empty(domains)) {
+    raw = raw.filter(entity => is.domain(entity, domains));
+  }
+  return raw;
+};
+
+export function IDByExtension({ hass, logger }: TServiceParams): IDByInterface {
+  // * byDomain
+  function byDomain<DOMAIN extends ALL_DOMAINS>(domain: DOMAIN) {
+    const MASTER_STATE = hass.entity._masterState();
+    return Object.keys(MASTER_STATE[domain] ?? {}).map(
+      id => `${domain}.${id}` as PICK_ENTITY<DOMAIN>,
+    );
+  }
+
+  // * unique_id
+  function unique_id<
+    UNIQUE_ID extends TUniqueId,
+    ENTITY_ID extends Extract<TUniqueIDMapping[UNIQUE_ID], ANY_ENTITY> = Extract<
+      TUniqueIDMapping[UNIQUE_ID],
+      ANY_ENTITY
+    >,
+  >(unique_id: UNIQUE_ID): ENTITY_ID {
+    hass.entity.warnEarly("byUniqueId");
+    const entity = hass.entity.registry.current.find(
+      i => i.unique_id === unique_id,
+    ) as EntityRegistryItem<ENTITY_ID>;
+    if (!entity) {
+      logger.error({ name: unique_id, unique_id }, `could not find an entity`);
+      return undefined;
+    }
+    return entity?.entity_id;
+  }
+
+  // * label
+  function label<LABEL extends TLabelId, DOMAIN extends ALL_DOMAINS>(
+    label: LABEL,
+    ...domains: DOMAIN[]
+  ) {
+    hass.entity.warnEarly("label");
+    return check(
+      hass.entity.registry.current
+        .filter(i => i.labels.includes(label))
+        .map(i => i.entity_id as PICK_FROM_LABEL<LABEL, DOMAIN>),
+      domains,
+    );
+  }
+
+  // * area
+  function area<AREA extends TAreaId, DOMAIN extends ALL_DOMAINS>(
+    area: AREA,
+    ...domains: DOMAIN[]
+  ) {
+    hass.entity.warnEarly("area");
+
+    // find entities are associated with the area directly
+    const fromEntity = hass.entity.registry.current
+      .filter(i => i.area_id === area)
+      .map(i => i.entity_id);
+
+    // identify devices
+    const devices = new Set(
+      hass.device.current.filter(device => device.area_id === area).map(i => i.id),
+    );
+
+    // extract entities associated with device, that have not been assigned to a room
+    const fromDevice = hass.entity.registry.current
+      .filter(entity => devices.has(entity.device_id) && is.empty(entity.area_id))
+      .map(i => i.entity_id);
+
+    return check(
+      // merge lists
+      is.unique([...fromEntity, ...fromDevice]),
+      domains,
+    ) as PICK_FROM_AREA<AREA, DOMAIN>[];
+  }
+
+  // * device
+  function device<DEVICE extends TDeviceId, DOMAIN extends ALL_DOMAINS>(
+    device: DEVICE,
+    ...domains: DOMAIN[]
+  ): PICK_FROM_DEVICE<DEVICE, DOMAIN>[] {
+    hass.entity.warnEarly("device");
+    return check(
+      hass.entity.registry.current
+        .filter(i => i.device_id === device)
+        .map(i => i.entity_id as PICK_FROM_DEVICE<DEVICE, DOMAIN>),
+      domains,
+    );
+  }
+
+  // * floor
+  function floor<FLOOR extends TFloorId, DOMAIN extends ALL_DOMAINS>(
+    floor: FLOOR,
+    ...domains: DOMAIN[]
+  ): PICK_FROM_FLOOR<FLOOR, DOMAIN>[] {
+    hass.entity.warnEarly("floor");
+    const areas = new Set<TAreaId>(
+      hass.area.current.filter(i => i.floor_id === floor).map(i => i.area_id),
+    );
+    return check(
+      hass.entity.registry.current
+        .filter(i => areas.has(i.area_id))
+        .map(i => i.entity_id as PICK_FROM_FLOOR<FLOOR, DOMAIN>),
+      domains,
+    );
+  }
+
+  // * platform
+  function platform<PLATFORM extends TPlatformId, DOMAIN extends ALL_DOMAINS>(
+    platform: PLATFORM,
+    ...domains: DOMAIN[]
+  ): PICK_FROM_PLATFORM<PLATFORM, DOMAIN>[] {
+    hass.entity.warnEarly("platform");
+    return check(
+      hass.entity.registry.current
+        .filter(i => i.platform === platform)
+        .map(i => i.entity_id as PICK_FROM_PLATFORM<PLATFORM, DOMAIN>),
+      domains,
+    );
+  }
+
+  return {
+    area,
+    device,
+    domain: byDomain,
+    floor,
+    label,
+    platform,
+    unique_id,
+  };
+}

package/src/extensions/index.ts

@@ -0,0 +1,16 @@
+export * from "./area.extension";
+export * from "./backup.extension";
+export * from "./call-proxy.extension";
+export * from "./config.extension";
+export * from "./device.extension";
+export * from "./entity.extension";
+export * from "./events.extension";
+export * from "./fetch-api.extension";
+export * from "./floor.extension";
+export * from "./id-by.extension";
+export * from "./internal.extension";
+export * from "./label.extension";
+export * from "./reference.extension";
+export * from "./registry.extension";
+export * from "./websocket-api.extension";
+export * from "./zone.extension";

package/src/extensions/internal.extension.ts

@@ -0,0 +1,145 @@
+import { FIRST, InternalError, is, TServiceParams } from "@digital-alchemy/core";
+import { createWriteStream } from "fs";
+import { pipeline } from "stream";
+import { promisify } from "util";
+
+import {
+  buildFilterString,
+  DownloadOptions,
+  FetchArguments,
+  FetcherOptions,
+  FetchProcessTypes,
+  FetchWith,
+  MaybeHttpError,
+  TFetchBody,
+} from "../helpers";
+
+const streamPipeline = promisify(pipeline);
+
+export function FetchInternals({ logger, context: parentContext }: TServiceParams) {
+  return ({ headers: base_headers, baseUrl: base_url, context: logContext }: FetcherOptions) => {
+    const capabilities: string[] = [];
+
+    if (!is.empty(capabilities)) {
+      logger.trace({ capabilities, name: logContext }, `initialized fetcher`);
+    }
+
+    function checkForHttpErrors<T extends unknown = unknown>(maybeError: MaybeHttpError): T {
+      if (
+        is.object(maybeError) &&
+        maybeError !== null &&
+        is.number(maybeError.statusCode) &&
+        is.string(maybeError.error)
+      ) {
+        // Log the error if needed
+        logger.error({ error: maybeError, name: logContext }, maybeError.message);
+
+        // Throw a FetchRequestError
+        // throw new FetchRequestError(maybeError);
+        throw new InternalError(logContext || parentContext, maybeError.error, maybeError.message);
+      }
+
+      return maybeError as T;
+    }
+
+    // #MARK: fetchHandleResponse
+    async function fetchHandleResponse<T extends unknown = unknown>(
+      process: FetchProcessTypes,
+      response: Response,
+    ): Promise<T> {
+      if (process === false || process === "raw") {
+        return response as T;
+      }
+      const text = await response.text();
+      if (process === "text") {
+        return text as unknown as T;
+      }
+      if (!["{", "["].includes(text.charAt(FIRST))) {
+        if (["OK"].includes(text)) {
+          logger.debug({ name: logContext, text }, "full response text");
+        } else {
+          // It's probably a coding error error, and not something a user did.
+          // Will try to keep the array up to date if any other edge cases pop up
+          logger.warn({ name: logContext, text }, `unexpected api Response`);
+        }
+        return text as T;
+      }
+      const parsed = JSON.parse(text);
+      return checkForHttpErrors<T>(parsed);
+    }
+
+    function fetchCreateUrl({ rawUrl, url, ...fetchWith }: FetchWith): string {
+      let out = url || "";
+      if (!rawUrl) {
+        const base = fetchWith.baseUrl || fetchWrapper.base_url;
+        out = base + url;
+      }
+      if (!is.empty(fetchWith.params)) {
+        out = `${out}?${buildFilterString(fetchWith)}`;
+      }
+      return out;
+    }
+
+    // #MARK: execFetch
+    async function exec<T, BODY extends TFetchBody = undefined>({
+      body,
+      headers = {},
+      method = "get",
+      process,
+      ...fetchWith
+    }: Partial<FetchArguments<BODY>>) {
+      const contentType = is.object(body) ? { "Content-Type": "application/json" } : {};
+      const result = await global.fetch(fetchCreateUrl(fetchWith), {
+        body: is.object(body) ? JSON.stringify(body) : body,
+        headers: {
+          ...contentType,
+          ...fetchWrapper.base_headers,
+          ...headers,
+        },
+        method,
+      });
+      return await fetchHandleResponse<T>(process, result);
+    }
+
+    async function download({
+      destination,
+      body,
+      headers = {},
+      method = "get",
+      ...fetchWith
+    }: DownloadOptions) {
+      const url: string = await fetchCreateUrl(fetchWith);
+      const response = await fetch(url, {
+        body: is.object(body) ? JSON.stringify(body) : body,
+        headers: { ...fetchWrapper.base_headers, ...headers },
+        method,
+      });
+
+      const stream = createWriteStream(destination);
+      await streamPipeline(response.body, stream);
+    }
+
+    // #MARK: return object
+    const fetchWrapper = {
+      base_headers,
+      base_url,
+      download,
+      exec,
+      /**
+       * @deprecated set base_url directly
+       */
+      setBaseUrl: (url: string) => (fetchWrapper.base_url = url),
+      /**
+       * @deprecated set base_headers directly
+       */
+      setHeaders: (headers: Record<string, string>) => (fetchWrapper.base_headers = headers),
+    };
+    return fetchWrapper;
+  };
+}
+
+export type TFetch = <T, BODY extends object = object>(
+  fetchWith: Partial<FetchArguments<BODY>>,
+) => Promise<T>;
+
+export type TDownload = (fetchWith: DownloadOptions) => Promise<void>;

package/src/extensions/label.extension.ts

@@ -0,0 +1,83 @@
+import { debounce, TServiceParams } from "@digital-alchemy/core";
+
+import { TLabelId } from "../dynamic";
+import {
+  EARLY_ON_READY,
+  HassLabelService,
+  LABEL_REGISTRY_UPDATED,
+  LabelDefinition,
+  LabelOptions,
+} from "../helpers";
+
+export function Label({
+  hass,
+  config,
+  logger,
+  lifecycle,
+  event,
+  context,
+}: TServiceParams): HassLabelService {
+  hass.socket.onConnect(async () => {
+    let loading = new Promise<void>(async done => {
+      hass.label.current = await hass.label.list();
+      loading = undefined;
+      done();
+    });
+    lifecycle.onReady(async () => loading && (await loading), EARLY_ON_READY);
+
+    hass.socket.subscribe({
+      context,
+      event_type: "label_registry_updated",
+      async exec() {
+        await debounce(LABEL_REGISTRY_UPDATED, config.hass.EVENT_DEBOUNCE_MS);
+        hass.label.current = await hass.label.list();
+        logger.debug(`label registry updated`);
+        event.emit(LABEL_REGISTRY_UPDATED);
+      },
+    });
+  });
+
+  async function create(details: LabelOptions) {
+    return await new Promise<void>(async done => {
+      event.once(LABEL_REGISTRY_UPDATED, done);
+      await hass.socket.sendMessage({
+        type: "config/label_registry/create",
+        ...details,
+      });
+    });
+  }
+
+  async function deleteLabel(label_id: TLabelId) {
+    return await new Promise<void>(async done => {
+      event.once(LABEL_REGISTRY_UPDATED, done);
+      await hass.socket.sendMessage({
+        label_id,
+        type: "config/label_registry/delete",
+      });
+    });
+  }
+
+  async function list() {
+    return await hass.socket.sendMessage<LabelDefinition[]>({
+      type: "config/label_registry/list",
+    });
+  }
+
+  async function update(details: LabelDefinition) {
+    return await new Promise<void>(async done => {
+      event.once(LABEL_REGISTRY_UPDATED, done);
+      await hass.socket.sendMessage({
+        type: "config/label_registry/update",
+        ...details,
+      });
+    });
+  }
+
+  return {
+    create,
+    current: [] as LabelDefinition[],
+    delete: deleteLabel,
+    list,
+    update,
+  };
+}