Add a new device_name method and improve existent device methods

Author: elchininet

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [5.12.0] - 2025-10-31
+
+- Add a new method to return the device name from an entity id or a device id (`device_name`)
+- Add support to send an entity id to the `device_attr` method
+- Add support to send an entity id to the `is_device_attr` method
+- Add support to send a device name to the `device_id` method
+
 ## [5.11.0] - 2025-10-30
 
 - Add a new parameter to the `trackTemplate` method to send extra variables

README.md

@@ -274,26 +274,38 @@ devices['706ad0ebe27e105d7cd0b73386deefdd'] // returns the device that matches t
 
 #### device_attr
 
-Method that returns the value of an attribute for the given device id or `undefined` if it doesn’t exist.
+Method that returns the value of an attribute for the given entity or device id. It returns `undefined` if the entity or the device doesn’t exist.
 
 ```javascript
+device_attr('sensor.my_sensor', 'manufacturer')
 device_attr('706ad0ebe27e105d7cd0b73386deefdd', 'manufacturer')
 ```
 
 #### is_device_attr
 
-Method to test if the value of a device attribute matches a value. It returns a `boolean`, if the device id doen‘t exist it returns `false`.
+Method to test if the value of a device attribute matches a value for a given entity or device id. It returns a `boolean`, if the entity or device doesn‘t exist it returns `false`.
 
 ```javascript
+is_device_attr('sensor.my_sensor', 'manufacturer', 'Synology')
 is_device_attr('706ad0ebe27e105d7cd0b73386deefdd', 'manufacturer', 'Synology')
 ```
 
 #### device_id
 
-Method to return the device id for a given entity id or `undefined` if the entity doesn‘t exist. 
+Method to return the device id for a given entity id or device name. It returns `undefined` if the entity or name doesn‘t exist. 
 
 ```javascript
 device_id('sensor.my_sensor')
+device_id('My lamp')
+```
+
+#### device_name
+
+Method to return the device name for a given device id or entity id. It returns `undefined` if the entity or device doesn‘t exist. 
+
+```javascript
+device_name('sensor.my_sensor')
+device_name('706ad0ebe27e105d7cd0b73386deefdd')
 ```
 
 #### areas

src/index.ts

@@ -211,6 +211,7 @@ class HomeAssistantJavaScriptTemplatesRenderer {
                 'device_attr',
                 'is_device_attr',
                 'device_id',
+                'device_name',
                 'areas',
                 'area_id',
                 'area_name',
@@ -242,6 +243,7 @@ class HomeAssistantJavaScriptTemplatesRenderer {
                 this._scopped.device_attr.bind(this._scopped),
                 this._scopped.is_device_attr.bind(this._scopped),
                 this._scopped.device_id.bind(this._scopped),
+                this._scopped.device_name.bind(this._scopped),
                 this._scopped.areas.bind(this._scopped),
                 this._scopped.area_id.bind(this._scopped),
                 this._scopped.area_name.bind(this._scopped),

src/types/index.ts

@@ -16,6 +16,7 @@ export interface Area {
 
 export interface Device {
     id: string;
+    name: string | null;
     area_id: string | null;
     [key: string]: unknown;
 }
@@ -131,9 +132,10 @@ export interface Scopped {
     is_entity_prop: (entityId: string, attr: string, value: unknown) => boolean;
     // devices
     devices: ProxiedDevices;
-    device_attr: (deviceId: string, attr: string) => unknown | undefined;
-    is_device_attr: (deviceId: string, attr: string, value: unknown) => boolean;
-    device_id: (entityId: string) => string | undefined;
+    device_attr: (entityIdOrDeviceId: string, attr: string) => unknown | undefined;
+    is_device_attr: (entityIdOrDeviceId: string, attr: string, value: unknown) => boolean;
+    device_id: (entityIdOrDeviceName: string) => string | undefined;
+    device_name: (entityIdOrDeviceId: string) => string | undefined;
     // areas
     areas: () => string[];
     area_id: (lookupValue: string) => string | undefined;

src/utilities/index.ts

@@ -256,15 +256,32 @@ export function createScoppedFunctions(
             }
         ),
 
-        device_attr(deviceId: string, attr: string): unknown {
-            return ha.hass.devices[deviceId]?.[attr];
+        device_attr(entityIdOrDeviceId: string, attr: string): unknown {
+            if (hasDot(entityIdOrDeviceId)) {
+                trackEntity(entityIdOrDeviceId);
+                const id = ha.hass.entities[entityIdOrDeviceId]?.device_id;
+                return ha.hass.devices[id]?.[attr];
+            }
+            return ha.hass.devices[entityIdOrDeviceId]?.[attr];
         },
-        is_device_attr(deviceId: string, attr: string, value: unknown): boolean {
-            return this.device_attr(deviceId, attr) === value;
+        is_device_attr(entityIdOrDeviceId: string, attr: string, value: unknown): boolean {
+            return this.device_attr(entityIdOrDeviceId, attr) === value;
         },
-        device_id(entityId: string): string {
-            trackEntity(entityId);
-            return ha.hass.entities[entityId]?.device_id;
+        device_id(entityIdOrDeviceName: string): string | undefined {
+            if (hasDot(entityIdOrDeviceName)) {
+                trackEntity(entityIdOrDeviceName);
+                return ha.hass.entities[entityIdOrDeviceName]?.device_id;
+            }
+            const device = devicesEntries().find((entry): boolean => entry[1].name === entityIdOrDeviceName);
+            return device?.[0];
+        },
+        device_name(entityIdOrDeviceId: string): string | undefined {
+            if (hasDot(entityIdOrDeviceId)) {
+                trackEntity(entityIdOrDeviceId);
+                const id = ha.hass.entities[entityIdOrDeviceId]?.device_id;
+                return ha.hass.devices[id]?.name;
+            }
+            return ha.hass.devices[entityIdOrDeviceId]?.name;
         },
 
         // ---------------------- Areas

tests/03 - basic-templates.test.ts

@@ -490,78 +490,214 @@ describe('Basic templates tests', () => {
 
     describe('device_attr', () => {
 
-        it('device_attr should return the proper value', () => {
-            expect(
-                compiler.renderTemplate('device_attr("706ad0ebe27e105d7cd0b73386deefdd", "manufacturer")')
-            ).toBe('Synology');
-            expect(
-                compiler.renderTemplate('device_attr("4d584585f0eb89172ce1a71c8b0e74ae", "model")')
-            ).toBe('HHCCJCY01');
-        });
+        describe('using an entity id', () => {
+
+            it('device_attr should return the proper value', () => {
+                expect(
+                    compiler.renderTemplate('device_attr("binary_sensor.koffiezetapparaat_aan", "manufacturer")')
+                ).toBe('Synology');
+                expect(
+                    compiler.renderTemplate('device_attr("light.woonkamer_lamp", "model")')
+                ).toBe('HHCCJCY01');
+            });
+
+            it('device_attr should return undefined if the attribute doesn\'t exist', () => {
+                expect(
+                    compiler.renderTemplate('device_attr("binary_sensor.koffiezetapparaat_verbonden", "attr")')
+                ).toBe(undefined);
+            });
+
+            it('device_attr should return undefined if the entity doesn\'t exist', () => {
+                expect(
+                    compiler.renderTemplate('device_attr("sensor.non_existent", "attr")')
+                ).toBe(undefined);
+                expect(consoleWarnMock).toHaveBeenCalledWith('Entity sensor.non_existent used in a JavaScript template doesn\'t exist');
+            });
 
-        it('device_attr should return undefined if the attribute doesn\'t exist', () => {
-            expect(
-                compiler.renderTemplate('device_attr("b8c1c9dd23cb82bbfa09b5657f41d04f", "attr")')
-            ).toBe(undefined);
         });
 
-        it('device_attr should return undefined if the device doesn\'t exist', () => {
-            expect(
-                compiler.renderTemplate('device_attr("012345", "attr")')
-            ).toBe(undefined);
+        describe('using a device id', () => {
+
+            it('device_attr should return the proper value', () => {
+                expect(
+                    compiler.renderTemplate('device_attr("706ad0ebe27e105d7cd0b73386deefdd", "manufacturer")')
+                ).toBe('Synology');
+                expect(
+                    compiler.renderTemplate('device_attr("4d584585f0eb89172ce1a71c8b0e74ae", "model")')
+                ).toBe('HHCCJCY01');
+            });
+
+            it('device_attr should return undefined if the attribute doesn\'t exist', () => {
+                expect(
+                    compiler.renderTemplate('device_attr("b8c1c9dd23cb82bbfa09b5657f41d04f", "attr")')
+                ).toBe(undefined);
+            });
+
+            it('device_attr should return undefined if the device doesn\'t exist', () => {
+                expect(
+                    compiler.renderTemplate('device_attr("012345", "attr")')
+                ).toBe(undefined);
+            });
+
         });
 
     });
 
     describe('is_device_attr', () => {
 
-        it('is_device_attr should return true if the attribute has the proper value', () => {
-            expect(
-                compiler.renderTemplate('is_device_attr("706ad0ebe27e105d7cd0b73386deefdd", "manufacturer", "Synology")')
-            ).toBe(true);
-    
-            expect(
-                compiler.renderTemplate('is_device_attr("4d584585f0eb89172ce1a71c8b0e74ae", "model", "HHCCJCY01")')
-            ).toBe(true);
+        describe('using an entity id', () => {
+
+            it('is_device_attr should return true if the attribute has the proper value', () => {
+                expect(
+                    compiler.renderTemplate('is_device_attr("binary_sensor.koffiezetapparaat_aan", "manufacturer", "Synology")')
+                ).toBe(true);
+        
+                expect(
+                    compiler.renderTemplate('is_device_attr("light.woonkamer_lamp", "model", "HHCCJCY01")')
+                ).toBe(true);
+            });
+
+            it('is_device_attr should return false if the attribute doesn\'t have the proper value', () => {
+                expect(
+                    compiler.renderTemplate('is_device_attr("sensor.slaapkamer_temperatuur", "area_id", "woonkamer")')
+                ).toBe(false);
+            });
+
+            it('is_device_attr should return false if the attribute doesn\'t exist', () => {
+                expect(
+                    compiler.renderTemplate('is_device_attr("binary_sensor.koffiezetapparaat_verbonden", "attr", "value")')
+                ).toBe(false);
+            });
+
+            it('is_device_attr should return false if the entity doesn\'t exist', () => {
+                expect(
+                    compiler.renderTemplate('is_device_attr("sensor.non_existent", "attr", "value")')
+                ).toBe(false);
+                expect(consoleWarnMock).toHaveBeenCalledWith('Entity sensor.non_existent used in a JavaScript template doesn\'t exist');
+            }); 
+
         });
 
-        it('is_device_attr should return false if the attribute doesn\'t have the proper value', () => {
-            expect(
-                compiler.renderTemplate('is_device_attr("dea1c4475b8dc901b7b33c7eac09896d", "area_id", "woonkamer")')
-            ).toBe(false);
+        describe('using a device id', () => {
+
+            it('is_device_attr should return true if the attribute has the proper value', () => {
+                expect(
+                    compiler.renderTemplate('is_device_attr("706ad0ebe27e105d7cd0b73386deefdd", "manufacturer", "Synology")')
+                ).toBe(true);
+        
+                expect(
+                    compiler.renderTemplate('is_device_attr("4d584585f0eb89172ce1a71c8b0e74ae", "model", "HHCCJCY01")')
+                ).toBe(true);
+            });
+
+            it('is_device_attr should return false if the attribute doesn\'t have the proper value', () => {
+                expect(
+                    compiler.renderTemplate('is_device_attr("dea1c4475b8dc901b7b33c7eac09896d", "area_id", "woonkamer")')
+                ).toBe(false);
+            });
+
+            it('is_device_attr should return false if the attribute doesn\'t exist', () => {
+                expect(
+                    compiler.renderTemplate('is_device_attr("b8c1c9dd23cb82bbfa09b5657f41d04f", "attr", "value")')
+                ).toBe(false);
+            });
+
+            it('is_device_attr should return false if the device doesn\'t exist', () => {
+                expect(
+                    compiler.renderTemplate('is_device_attr("012345", "attr", "value")')
+                ).toBe(false);
+            }); 
+
         });
 
-        it('is_device_attr should return false if the attribute doesn\'t exist', () => {
-            expect(
-                compiler.renderTemplate('is_device_attr("b8c1c9dd23cb82bbfa09b5657f41d04f", "attr", "value")')
-            ).toBe(false);
+    });
+
+    describe('device_id', () => {
+
+        describe('using an entity id', () => {
+
+            it('device_id should return the proper device id', () => {
+                expect(
+                    compiler.renderTemplate('device_id("light.woonkamer_lamp")')
+                ).toBe('4d584585f0eb89172ce1a71c8b0e74ae');
+        
+                expect(
+                    compiler.renderTemplate('device_id("binary_sensor.internetverbinding")')
+                ).toBe('a121a9414241f03ce6b3108b2716f9be');
+            });
+
+            it('device_id should return undefined if the entity id doesn\'t exist', () => {
+                expect(
+                    compiler.renderTemplate('device_id("sensor.non_existent")')
+                ).toBe(undefined);
+                expect(consoleWarnMock).toHaveBeenCalledWith('Entity sensor.non_existent used in a JavaScript template doesn\'t exist');
+            });
+
         });
 
-        it('is_device_attr should return false if the device doesn\'t exist', () => {
-            expect(
-                compiler.renderTemplate('is_device_attr("012345", "attr", "value")')
-            ).toBe(false);
-        });       
+        describe('using a device name', () => {
+
+            it('device_id should return the proper device id', () => {
+                expect(
+                    compiler.renderTemplate('device_id("Woonkamer Lamp")')
+                ).toBe('4d584585f0eb89172ce1a71c8b0e74ae');
+        
+                expect(
+                    compiler.renderTemplate('device_id("Eetkamer lampje")')
+                ).toBe('720a719fe7db1460b0e4cc9ffbb1488d');
+            });
+
+            it('device_id should return undefined if the device name doesn\'t exist', () => {
+                expect(
+                    compiler.renderTemplate('device_id("My camera")')
+                ).toBe(undefined);
+            });
+
+        });
 
     });
 
-    describe('device_id', () => {
+    describe('device_name', () => {
+
+        describe('using an entity id', () => {
+
+            it('device_name should return the proper device name', () => {
+                expect(
+                    compiler.renderTemplate('device_name("binary_sensor.koffiezetapparaat_aan")')
+                ).toBe('Mijn Koffiezetapparaat');
+        
+                expect(
+                    compiler.renderTemplate('device_name("light.eetkamer_lampje")')
+                ).toBe('Eetkamer lampje');
+            });
+
+            it('device_name should return undefined if the entity id doesn\'t exist', () => {
+                expect(
+                    compiler.renderTemplate('device_name("sensor.non_existent")')
+                ).toBe(undefined);
+                expect(consoleWarnMock).toHaveBeenCalledWith('Entity sensor.non_existent used in a JavaScript template doesn\'t exist');
+            });
 
-        it('device_id should return the proper device id', () => {
-            expect(
-                compiler.renderTemplate('device_id("light.woonkamer_lamp")')
-            ).toBe('4d584585f0eb89172ce1a71c8b0e74ae');
-    
-            expect(
-                compiler.renderTemplate('device_id("binary_sensor.internetverbinding")')
-            ).toBe('a121a9414241f03ce6b3108b2716f9be');
         });
 
-        it('device_id should return undefined if the device doesn\'t exist', () => {
-            expect(
-                compiler.renderTemplate('device_id("sensor.non_existent")')
-            ).toBe(undefined);
-            expect(consoleWarnMock).toHaveBeenCalledWith('Entity sensor.non_existent used in a JavaScript template doesn\'t exist');
+        describe('using a device id', () => {
+
+            it('device_name using a device id should return the proper device name', () => {
+                expect(
+                    compiler.renderTemplate('device_name("4d584585f0eb89172ce1a71c8b0e74ae")')
+                ).toBe('Woonkamer Lamp');
+        
+                expect(
+                    compiler.renderTemplate('device_name("720a719fe7db1460b0e4cc9ffbb1488d")')
+                ).toBe('Eetkamer lampje');
+            });
+
+            it('device_name should return undefined if the device id doesn\'t exist', () => {
+                expect(
+                    compiler.renderTemplate('device_name("4d58451c8b0e74ae85f0eb89172ce1a7")')
+                ).toBe(undefined);
+            });
+
         });
 
     });