Major upgrade

eslint.config.mjs

@@ -63,6 +63,7 @@ export default [
       "unicorn/prefer-module": "off",
       "@typescript-eslint/no-magic-numbers": "warn",
       "unicorn/no-object-as-default-parameter": "off",
+      "@typescript-eslint/no-floating-promises": "error",
       "unicorn/no-null": "off",
       "sonarjs/no-empty-function": "off",
       "sonarjs/no-unused-expressions": "off",

package.json

@@ -3,7 +3,7 @@
   "name": "@digital-alchemy/synapse",
   "repository": "https://github.com/Digital-Alchemy-TS/synapse",
   "homepage": "https://docs.digital-alchemy.app/Synapse",
-  "version": "24.11.4",
+  "version": "24.12.1",
   "scripts": {
     "start:mock": "tsx src/mock/main.mts",
     "build": "rm -rf dist; tsc",
@@ -28,7 +28,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "better-sqlite3": "^11.5.0"
+    "better-sqlite3": "^11.7.0"
   },
   "peerDependencies": {
     "@digital-alchemy/core": "*",
@@ -38,40 +38,43 @@
     "uuid": "*"
   },
   "devDependencies": {
-    "@cspell/eslint-plugin": "^8.16.0",
-    "@digital-alchemy/core": "^24.11.3",
-    "@digital-alchemy/hass": "^24.11.3",
-    "@eslint/compat": "^1.2.3",
+    "@cspell/eslint-plugin": "^8.16.1",
+    "@digital-alchemy/core": "^24.11.4",
+    "@digital-alchemy/hass": "^24.11.4",
+    "@eslint/compat": "^1.2.4",
     "@eslint/eslintrc": "^3.2.0",
-    "@eslint/js": "^9.15.0",
+    "@eslint/js": "^9.16.0",
     "@types/better-sqlite3": "^7.6.12",
-    "@types/node": "^22.9.1",
+    "@types/bun": "^1.1.14",
+    "@types/node": "^22.10.1",
     "@types/node-cron": "^3.0.11",
     "@types/uuid": "^10.0.0",
     "@types/ws": "^8.5.13",
-    "@typescript-eslint/eslint-plugin": "8.15.0",
-    "@typescript-eslint/parser": "8.15.0",
+    "@typescript-eslint/eslint-plugin": "8.17.0",
+    "@typescript-eslint/parser": "8.17.0",
+    "bun": "^1.1.38",
+    "bun-types": "^1.1.38",
     "dayjs": "^1.11.13",
-    "dotenv": "^16.4.5",
-    "eslint": "9.15.0",
+    "dotenv": "^16.4.7",
+    "eslint": "9.16.0",
     "eslint-config-prettier": "9.1.0",
     "eslint-plugin-import": "^2.31.0",
     "eslint-plugin-jsonc": "^2.18.2",
     "eslint-plugin-no-unsanitized": "^4.1.2",
     "eslint-plugin-prettier": "^5.2.1",
     "eslint-plugin-security": "^3.0.1",
     "eslint-plugin-simple-import-sort": "^12.1.1",
-    "eslint-plugin-sonarjs": "^2.0.4",
+    "eslint-plugin-sonarjs": "^3.0.1",
     "eslint-plugin-sort-keys-fix": "^1.1.2",
     "eslint-plugin-unicorn": "^56.0.1",
     "node-cron": "^3.0.3",
-    "prettier": "^3.3.3",
+    "prettier": "^3.4.2",
     "tsx": "^4.19.2",
-    "type-fest": "^4.27.0",
-    "typescript": "^5.7.0-beta",
+    "type-fest": "^4.30.0",
+    "typescript": "^5.7.2",
     "uuid": "^11.0.3",
-    "vitest": "^2.1.5",
+    "vitest": "^2.1.8",
     "ws": "^8.18.0"
   },
-  "packageManager": "[email protected].1"
+  "packageManager": "[email protected].3"
 }

src/helpers/base-domain.mts

@@ -3,14 +3,30 @@ import { TRawDomains } from "@digital-alchemy/hass";
 import { createHash } from "crypto";
 import { EmptyObject } from "type-fest";
 
-import { EntityConfigCommon } from "./common-config.mts";
+import { EntityConfigCommon, NonReactive } from "./common-config.mts";
 import { TSynapseId } from "./utility.mts";
 
 export type RemovableCallback<DATA extends unknown = unknown> = (
   data: DATA,
   remove: () => void,
 ) => TBlackHole;
 
+export type TSerialize<
+  CONFIGURATION extends object = object,
+  SERIALIZE_TYPES extends unknown = unknown,
+> = {
+  serialize: (
+    property: keyof CONFIGURATION,
+    data: SERIALIZE_TYPES,
+    options: CONFIGURATION,
+  ) => string;
+  unserialize: (
+    property: keyof CONFIGURATION,
+    data: string,
+    options: CONFIGURATION,
+  ) => SERIALIZE_TYPES;
+};
+
 export type CreateRemovableCallback<DATA extends unknown = unknown> = (
   callback: RemovableCallback<DATA>,
 ) => { remove: () => void };
@@ -46,21 +62,7 @@ export type DomainGeneratorOptions<
    * ensure that data is valid before handing off to internals
    */
   validate?: (current: CONFIGURATION, key: keyof CONFIGURATION, value: unknown) => void | never;
-} & (
-  | {
-      serialize: (
-        property: keyof CONFIGURATION,
-        data: SERIALIZE_TYPES,
-        options: CONFIGURATION,
-      ) => string;
-      unserialize: (
-        property: keyof CONFIGURATION,
-        data: string,
-        options: CONFIGURATION,
-      ) => SERIALIZE_TYPES;
-    }
-  | EmptyObject
-);
+} & (TSerialize<CONFIGURATION, SERIALIZE_TYPES> | EmptyObject);
 
 export type TEventMap = Record<string, object>;
 
@@ -69,9 +71,10 @@ export type AddEntityOptions<
   EVENT_MAP extends Record<string, object>,
   ATTRIBUTES extends object,
   LOCALS extends object,
+  DATA extends object,
 > = {
   context: TContext;
-} & EntityConfigCommon<ATTRIBUTES, LOCALS> &
+} & EntityConfigCommon<ATTRIBUTES, LOCALS, DATA> &
   CONFIGURATION &
   Partial<{
     [EVENT in keyof EVENT_MAP]: RemovableCallback<EVENT_MAP[EVENT]>;
@@ -100,3 +103,12 @@ export const formatObjectId = (input: string) =>
     .replaceAll(/_+/g, "_");
 
 export const LATE_READY = -1;
+
+export type CallbackData<
+  LOCALS extends object,
+  ATTRIBUTES extends object,
+  EXTRA extends object = {},
+> = {
+  locals: LOCALS;
+  attributes: ATTRIBUTES;
+} & NonReactive<Omit<EXTRA, "managed">>;

src/helpers/common-config.mts

@@ -12,7 +12,11 @@ import { CreateRemovableCallback, TEventMap } from "./base-domain.mts";
 import { TSynapseEntityStorage } from "./storage.mts";
 import { TSynapseDeviceId } from "./utility.mts";
 
-export type EntityConfigCommon<ATTRIBUTES extends object, LOCALS extends object> = {
+export type EntityConfigCommon<
+  ATTRIBUTES extends object,
+  LOCALS extends object,
+  DATA extends object,
+> = {
   /**
    * Use a different device to register this entity
    */
@@ -33,8 +37,8 @@ export type EntityConfigCommon<ATTRIBUTES extends object, LOCALS extends object>
    * This ID uniquely identifies the entity, through `entity_id` renames
    */
   unique_id?: string;
-  disabled?: SettableConfiguration<boolean>;
-  icon?: SettableConfiguration<string>;
+  disabled?: SettableConfiguration<boolean, DATA>;
+  icon?: SettableConfiguration<string, DATA>;
   /**
    * An entity with a category will:
    * - Not be exposed to cloud, Alexa, or Google Assistant components
@@ -62,31 +66,73 @@ export type EntityConfigCommon<ATTRIBUTES extends object, LOCALS extends object>
    * can be used as a sqlite backed cache for entity specific data
    */
   locals?: LOCALS;
+  /**
+   * Automatically trigger reactive config updates in response to updates from these entities
+   *
+   * List gets merged with `onUpdate` array in the configs, is convenient shorthand
+   */
+  bind?: Updatable<DATA>[];
 };
 
 export const isCommonConfigKey = <ATTRIBUTES extends object, LOCALS extends object>(
   key: string,
-): key is keyof EntityConfigCommon<ATTRIBUTES, LOCALS> => COMMON_CONFIG_KEYS.has(key);
+): key is keyof EntityConfigCommon<ATTRIBUTES, LOCALS, object> => COMMON_CONFIG_KEYS.has(key);
+
+export type SettableConfiguration<TYPE extends unknown, DATA extends object> =
+  /**
+   * Straight provide the value.
+   * If this changes in the definition (hard coded value usually), then the entity config will be reset
+   *
+   * This option can be used with assignments
+   *
+   * ```typescript
+   * entity.field = new_value;
+   * ```
+   */
+  | TYPE
+  // Verbose form
+  | ReactiveConfig<TYPE, DATA>
+  // Equiv of the `current` for the verbose reactive config
+  // If you don't need the other options (or prefer bind), this works great 👍
+  | ((data: DATA) => TYPE);
 
-export type SettableConfiguration<TYPE extends unknown> = TYPE | ReactiveConfig<TYPE>;
+export type Updatable<DATA extends object> = {
+  onUpdate: (callback: (data: DATA) => TBlackHole) => void;
+};
 
-export type ReactiveConfig<TYPE extends unknown = unknown> = {
+/**
+ * > **NOTE**: `onUpdate` list is merged with the `bind` array that is provided to the entity
+ * ```typescript
+ * {
+ *   icon: {
+ *     current() {
+ *       return someLogic ? "mdi:cookie-clock" : "mdi:cookie-alert-outline";
+ *     },
+ *     onUpdate: [hassEntityReference, synapseEntityReference],
+ *     // every 30 seconds by default
+ *     schedule: CronExpression.EVERY_SECOND,
+ *   },
+ * }
+ * ```
+ */
+export type ReactiveConfig<TYPE extends unknown = unknown, DATA extends object = object> = {
   /**
    * Update immediately in response to entity updates
    */
-  onUpdate?: { onUpdate: (callback: () => TBlackHole) => void }[];
-
+  onUpdate?: Updatable<DATA>[];
   /**
    * Every 30s by default
    */
   schedule?: CronExpression | string;
-
   /**
    * Calculate current value
    */
-  current(): TYPE;
+  current(data: DATA): TYPE;
 };
 
+export const isShortReactiveConfig = (key: string, value: unknown): value is ReactiveConfig =>
+  is.function(value) && key !== "attributes" && !NO_LIVE_UPDATE.has(key);
+
 export const isReactiveConfig = (key: string, value: unknown): value is ReactiveConfig =>
   is.object(value) &&
   is.function((value as { current: () => void }).current) &&
@@ -127,13 +173,18 @@ export type NON_SETTABLE =
 
 export type NonReactive<CONFIGURATION extends object> = {
   [KEY in Extract<keyof CONFIGURATION, string>]: CONFIGURATION[KEY] extends SettableConfiguration<
-    infer TYPE
+    infer TYPE,
+    object
   >
     ? TYPE
     : CONFIGURATION[KEY];
 };
 
-export type CommonMethods<CONFIGURATION extends object, LOCALS extends object> = {
+export type CommonMethods<
+  CONFIGURATION extends object,
+  LOCALS extends object,
+  DATA extends object,
+> = {
   /**
    * Look up the actual entity_id that is mapped to this entity by unique_id
    */
@@ -173,7 +224,7 @@ export type CommonMethods<CONFIGURATION extends object, LOCALS extends object> =
   /**
    * @internal
    */
-  storage: TSynapseEntityStorage<CONFIGURATION & EntityConfigCommon<object, LOCALS>>;
+  storage: TSynapseEntityStorage<CONFIGURATION & EntityConfigCommon<object, LOCALS, DATA>>;
   /**
    * add a listener that can be removed with the removeAllListeners call
    *
@@ -202,16 +253,17 @@ type ProxyBase<
   EVENT_MAP extends TEventMap,
   ATTRIBUTES extends object,
   LOCALS extends object,
-> = CommonMethods<CONFIGURATION, LOCALS> &
+  DATA extends object,
+> = CommonMethods<CONFIGURATION, LOCALS, DATA> &
   NonReactive<CONFIGURATION> &
   BuildCallbacks<EVENT_MAP> &
-  EntityConfigCommon<ATTRIBUTES, LOCALS> & {
+  EntityConfigCommon<ATTRIBUTES, LOCALS, DATA> & {
     /**
      * @internal
      *
      * duplicate the entity proxy, used for management of listeners
      */
-    child: (context: TContext) => ProxyBase<CONFIGURATION, EVENT_MAP, ATTRIBUTES, LOCALS>;
+    child: (context: TContext) => ProxyBase<CONFIGURATION, EVENT_MAP, ATTRIBUTES, LOCALS, DATA>;
   };
 
 /**
@@ -224,7 +276,8 @@ export type SynapseEntityProxy<
   EVENT_MAP extends TEventMap,
   ATTRIBUTES extends object,
   LOCALS extends object,
-  PROXY = ProxyBase<CONFIGURATION, EVENT_MAP, ATTRIBUTES, LOCALS>,
+  DATA extends object,
+  PROXY = ProxyBase<CONFIGURATION, EVENT_MAP, ATTRIBUTES, LOCALS, DATA>,
 > = Omit<PROXY, Extract<keyof PROXY, NON_SETTABLE>>;
 
 export type BuildCallbacks<EVENT_MAP extends TEventMap> = {
@@ -233,4 +286,10 @@ export type BuildCallbacks<EVENT_MAP extends TEventMap> = {
     string
   > as CamelCase<`on-${EVENT_NAME}`>]: CreateRemovableCallback<EVENT_MAP[EVENT_NAME]>;
 };
-export type GenericSynapseEntity = SynapseEntityProxy<object, TEventMap, object, object>;
+export type GenericSynapseEntity<DATA extends object = object> = SynapseEntityProxy<
+  object,
+  TEventMap,
+  object,
+  object,
+  DATA
+>;

src/helpers/sensor.mts

@@ -341,7 +341,7 @@ type NumberSensors = (
    *
    * Note that the `datetime.datetime` returned by the `last_reset` property will be converted to an ISO 8601-formatted string when the entity's state attributes are updated. When changing `last_reset`, the `state` must be a valid number.
    */
-  last_reset?: SettableConfiguration<Dayjs>;
+  last_reset?: SettableConfiguration<Dayjs, object>;
 
   /**
    * Type of state.
@@ -359,7 +359,8 @@ export type SensorConfiguration<
   ATTRIBUTES extends object,
   LOCALS extends object,
   STATE_TYPE extends string | number | Date | Dayjs,
-> = EntityConfigCommon<ATTRIBUTES, LOCALS> &
+  DATA extends object,
+> = EntityConfigCommon<ATTRIBUTES, LOCALS, DATA> &
   SensorDeviceClasses<STATE_TYPE> & {
-    state?: SettableConfiguration<STATE_TYPE>;
+    state?: SettableConfiguration<STATE_TYPE, DATA>;
   };