Add a new method state_translated and improve is_state method

Author: elchininet

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [5.9.0] - 2025-07-13
+
+- Add a new method `state_translated` to return the translated state value of an entity
+- Improve the `is_state` function to accept also an array as a value to compare
+
 ## [5.8.0] - 2025-06-24
 
 - Improve the `states` function with an optional object with options (`with_unit` and `rounded`)

README.md

@@ -180,12 +180,22 @@ states.sensor // returns an object containing all the entities states of the 'se
 >[!TIP]
 >Avoid using `states['sensor.slaapkamer_temperatuur'].state` or `states.sensor.slaapkamer_temperatuur.state`. Use `states('sensor.slaapkamer_temperatuur')` instead, which will return `undefined` if the device id doesn‘t exist or the entity isn’t ready yet (the former will throw an error). If you still want to use them it is advisable to use the [Optional chaining operator], e.g. `states['sensor.slaapkamer_temperatuur']?.state` or `states.sensor?.slaapkamer_temperatuur?.state`.
 
+#### state_translated
+
+Method to return a translated state of an entity using a language that is currently configured in the general settings. If the entity id doesn‘t exist it returns `undefined`.
+
+```javascript
+states('device_tracker.paulus'); // not_home
+state_translated('device_tracker.paulus') // Away
+```
+
 #### is_state
 
-Method to check if the state of an entity is equal to a certain value. It returns a `boolean`. If the entity id doesn‘t exist it returns `false`.
+Method to check if the state of an entity is equal to a certain value or it is contained inside a list of values. It returns a `boolean`. If the entity id doesn‘t exist it returns `false`.
 
 ```javascript
-is_state('device_tracker.paulus', 'not_home')
+is_state('device_tracker.paulus', 'not_home') // check for a single value
+is_state('device_tracker.paulus', ['not_home', 'work']) // check for a list of values
 ```
 
 #### state_attr

src/index.ts

@@ -195,6 +195,7 @@ class HomeAssistantJavaScriptTemplatesRenderer {
             const templateFunction = new Function(
                 'hass',
                 'states',
+                'state_translated',
                 'is_state',
                 'state_attr',
                 'is_state_attr',
@@ -225,6 +226,7 @@ class HomeAssistantJavaScriptTemplatesRenderer {
             return templateFunction(
                 this._scopped.hass,
                 this._scopped.states,
+                this._scopped.state_translated.bind(this._scopped),
                 this._scopped.is_state.bind(this._scopped),
                 this._scopped.state_attr.bind(this._scopped),
                 this._scopped.is_state_attr.bind(this._scopped),

src/types/index.ts

@@ -45,6 +45,7 @@ export interface Hass {
     states: Record<string, State>;
     user: User;
     language: string;
+    formatEntityState: (state: State) => string | undefined;
 }
 
 export interface HomeAssistant extends HTMLElement {
@@ -109,7 +110,8 @@ export interface Scopped {
     hass: Hass;
     // states
     states: ProxiedStates;
-    is_state: (entityId: string, value: string) => boolean;
+    state_translated: (entityId: string) => string;
+    is_state: (entityId: string, value: string | string[]) => boolean;
     state_attr: (entityId: string, attr: string) => unknown | undefined;
     is_state_attr: (entityId: string, attr: string, value: unknown) => boolean;
     has_value: (entityId: string) => boolean;

src/utilities/index.ts

@@ -161,8 +161,20 @@ export function createScoppedFunctions(
                 }
             }
         ),
-        is_state(entityId: string, value: string): boolean {
+        state_translated(entityId: string): string | undefined {
             trackEntity(entityId);
+            if (ha.hass.states[entityId]) {
+                return ha.hass.formatEntityState(ha.hass.states[entityId]);
+            }
+            return undefined;
+        },
+        is_state(entityId: string, value: string | string[]): boolean {
+            trackEntity(entityId);
+            if (Array.isArray(value)) {
+                return value.some((valueItem: string): boolean => {
+                    return ha.hass.states[entityId]?.state === valueItem;
+                });
+            }
             return ha.hass.states[entityId]?.state === value;
         },
         state_attr(entityId: string, attr: string): unknown {

tests/03 - basic-templates.test.ts

@@ -17,6 +17,7 @@ describe('Basic templates tests', () => {
     });
 
     afterEach(() => {
+        jest.resetAllMocks();
         consoleWarnMock.mockRestore();
     });
 
@@ -194,25 +195,71 @@ describe('Basic templates tests', () => {
 
     });
 
-    describe('is_state', () => {
+    describe('state_translated', () => {
 
-        it('is_state should return true if the value coincides', () => {
-            expect(
-                compiler.renderTemplate('is_state("sensor.slaapkamer_luchtvochtigheid", "45")')
-            ).toBe(true);
+        describe.each(
+            Object.keys(HASS.states)
+        )('for entity id %s', (entityId: string) => {
+            it('should send the proper state to the formatEntityState function', () => {
+                compiler.renderTemplate(`state_translated("${entityId}")`);
+                expect(HASS.formatEntityState).toHaveBeenNthCalledWith(1, HASS.states[entityId]);
+            });
         });
 
-        it('is_state should return false if the value doesn\'t coincide', () => {
-            expect(
-                compiler.renderTemplate('is_state("sensor.slaapkamer_temperatuur", "10")')
-            ).toBe(false);
+        it('should return undefined if the entity id doesn\'t exist', () => {
+            const result = compiler.renderTemplate('state_translated("sensor.non_existent")');
+            expect(HASS.formatEntityState).not.toHaveBeenCalled();
+            expect(result).toBeUndefined();
         });
 
-        it('is_state should return false if the entity id doesn\'t exist', () => {
-            expect(
-                compiler.renderTemplate('is_state("sensor.non_existent", "10")')
-            ).toBe(false);
-            expect(consoleWarnMock).toHaveBeenCalledWith('Entity sensor.non_existent used in a JavaScript template doesn\'t exist');
+    });
+
+    describe('is_state', () => {
+
+        describe('value as string', () => {
+
+            it('is_state should return true if the value coincides', () => {
+                expect(
+                    compiler.renderTemplate('is_state("sensor.slaapkamer_luchtvochtigheid", "45")')
+                ).toBe(true);
+            });
+
+            it('is_state should return false if the value doesn\'t coincide', () => {
+                expect(
+                    compiler.renderTemplate('is_state("sensor.slaapkamer_temperatuur", "10")')
+                ).toBe(false);
+            });
+
+            it('is_state should return false if the entity id doesn\'t exist', () => {
+                expect(
+                    compiler.renderTemplate('is_state("sensor.non_existent", "45")')
+                ).toBe(false);
+                expect(consoleWarnMock).toHaveBeenCalledWith('Entity sensor.non_existent used in a JavaScript template doesn\'t exist');
+            });
+
+        });
+
+        describe('value as array', () => {
+
+            it('is_state should return true if the value is contained inside the array', () => {
+                expect(
+                    compiler.renderTemplate('is_state("sensor.slaapkamer_luchtvochtigheid", ["15", "45", "56"])')
+                ).toBe(true);
+            });
+
+            it('is_state should return false if the value isn\'t contained inside the array', () => {
+                expect(
+                    compiler.renderTemplate('is_state("sensor.slaapkamer_temperatuur", ["5", "10", "28", "100"])')
+                ).toBe(false);
+            });
+
+            it('is_state should return false if the entity id doesn\'t exist', () => {
+                expect(
+                    compiler.renderTemplate('is_state("sensor.non_existent", ["17", "45", "2"])')
+                ).toBe(false);
+                expect(consoleWarnMock).toHaveBeenCalledWith('Entity sensor.non_existent used in a JavaScript template doesn\'t exist');
+            });
+
         });
 
     });

tests/constants.ts

@@ -157,7 +157,8 @@ export const HASS: Hass = {
         is_owner: false,
         name: 'ElChiniNet'
     },
-    language: 'en'
+    language: 'en',
+    formatEntityState: jest.fn()
 };
 
 export const HOME_ASSISTANT_ELEMENT = {