ha-nunjucks 1.4.0 → 1.5.0

package/README.md

@@ -54,6 +54,34 @@ const context = {
 const renderedString = renderTemplate(this.hass, templateString, context);
 ```
 
+`renderTemplate` will try to validate that inputs contain valid templates by default using the exported function `hasTemplate`. You can disable this by setting the fourth argument of `renderTemplate` to `false`. This way you can perform this check yourself before any additional templating setup you perform in your code.
+
+```typescript
+import { hasTemplate, renderTemplate } from 'ha-nunjucks';
+
+if (!hasTemplate(templateString)) {
+  return templateString;
+}
+
+const context = {
+  foo: 'bar',
+  doThing(thing: string) {
+    return `doing ${thing}!`;
+  },
+  config: {
+    entity: 'foo.bar',
+    attribute: 'baz_bah',
+  },
+};
+
+const renderedString = renderTemplate(
+  this.hass,
+  templateString,
+  context,
+  false,
+);
+```
+
 ### Return Types
 
 `renderTemplate` will return a string unless the result is `true` or `false` (_not_ case sensitive), in which case it will return a boolean.
@@ -115,6 +143,10 @@ Functions used to determine an entity's state or an attribute.
 | state_translated      | function, filter | entity_id, state (optional)                 | Returns the formatted and translated state of an entity or provided state using a language that is currently configured in the general settings.                     |
 | attr_name_translated  | function, filter | entity_id, attr_name                        | Returns the formatted and translated attribute name of an entity using a language that is currently configured in the general settings.                              |
 | attr_value_translated | function, filter | entity_id, attr_name, attr_value (optional) | Returns the formatted and translated attribute value of an entity or provided attribute value using a language that is currently configured in the general settings. |
+| number_translated     | function, filter | value                                       | Returns the formatted and translated input number using a language that is currently configured in the general settings.                                             |
+| date_translated       | function, filter | value                                       | Returns the formatted and translated input date or datetime as a date using a language that is currently configured in the general settings.                         |
+| time_translated       | function, filter | value                                       | Returns the formatted and translated input time or datetime as a time using a language that is currently configured in the general settings.                         |
+| datetime_translated   | function, filter | value                                       | Returns the formatted and translated input datetime using a language that is currently configured in the general settings.                                           |
 
 ### [Groups](https://www.home-assistant.io/docs/configuration/templating/#working-with-groups)
 
@@ -164,7 +196,7 @@ Functions used to determine an entity's state or an attribute.
 
 ### [Labels](https://www.home-assistant.io/docs/configuration/templating/#labels)
 
-**NOTE**: Labels are not available in the `hass` object and must be retrieved asynchronously from the Home Assistant backend the first time `renderTemplate` is called. Since this package is otherwise synchronous, this can cause a race condition where no labels are found the first time `renderTemplate` is run. This generally resolves itself once the template re-renders.
+**NOTE**: Labels are not available in the `hass` object and must be retrieved asynchronously from the Home Assistant backend the first time `ha-nunjucks` is imported. Since this package is otherwise synchronous, this can cause a race condition where no labels are found the first time `renderTemplate` is run. This generally resolves itself once the template re-renders.
 
 | Name           | Type             | Arguments               | Description                                                                                |
 | -------------- | ---------------- | ----------------------- | ------------------------------------------------------------------------------------------ |

package/dist/filters.js

@@ -10,7 +10,7 @@ import { label_areas, label_devices, label_entities, label_id, label_name, label
 import { str } from './utils/miscellaneous';
 import { acos, add, asin, atan, atan2, average, bitwise_and, bitwise_not, bitwise_or, bitwise_xor, bool, cos, is_number, log, max, median, min, multiply, ord, sin, sqrt, statistical_mode, tan, } from './utils/numeric';
 import { regex_findall, regex_findall_index, regex_replace, } from './utils/regexp';
-import { attr_name_translated, attr_value_translated, state_translated, } from './utils/state_translated';
+import { attr_name_translated, attr_value_translated, date_translated, datetime_translated, number_translated, state_translated, time_translated, } from './utils/state_translated';
 import { has_value, state_attr, states } from './utils/states';
 import { as_datetime, as_local, as_timestamp, time_since, time_until, timestamp_custom, timestamp_local, timestamp_utc, today_at, } from './utils/time';
 export function addFilters(env) {
@@ -74,6 +74,9 @@ const FILTERS = {
     timestamp_local,
     timestamp_utc,
     timestamp_custom,
+    date_translated,
+    time_translated,
+    datetime_translated,
     // To/From JSON
     to_json,
     from_json,
@@ -107,6 +110,7 @@ const FILTERS = {
     ord,
     multiply,
     add,
+    number_translated,
     // Regular Expressions
     regex_replace,
     regex_findall,

package/dist/globals.js

@@ -9,7 +9,7 @@ import { integration_entities } from './utils/integrations';
 import { label_areas, label_devices, label_entities, label_id, label_name, labels, } from './utils/labels';
 import { match_media, str } from './utils/miscellaneous';
 import { acos, asin, atan, atan2, average, bool, cos, e, float, inf, int, is_number, log, max, median, min, pi, sin, sqrt, statistical_mode, tan, tau, } from './utils/numeric';
-import { attr_name_translated, attr_value_translated, state_translated, } from './utils/state_translated';
+import { attr_name_translated, attr_value_translated, date_translated, datetime_translated, number_translated, state_translated, time_translated, } from './utils/state_translated';
 import { has_value, is_state, is_state_attr, state_attr, states, } from './utils/states';
 import { as_datetime, as_local, as_timedelta, as_timestamp, now, strptime, time_since, time_until, today_at, utcnow, } from './utils/time';
 import { list, set } from './utils/type_conversions';
@@ -95,6 +95,9 @@ const GLOBALS = {
     time_since,
     time_until,
     as_timedelta,
+    date_translated,
+    time_translated,
+    datetime_translated,
     // Numeric,
     float,
     is_number,
@@ -114,6 +117,7 @@ const GLOBALS = {
     average,
     median,
     statistical_mode,
+    number_translated,
     // Type Conversions
     set,
     list,

package/dist/index.d.ts

@@ -4,6 +4,13 @@ import { HomeAssistant } from './models/interfaces/hass';
  * @param {HomeAssistant} hass The Home Assistant object
  * @param {string} str The template string to render
  * @param {object} [context] Additional context to expose to nunjucks
+ * @param {boolean} [validate=true] Validate that the input contains a template.
  * @returns {string | boolean} The rendered template string if a string was provided, otherwise the unaltered input
  */
-export declare function renderTemplate(hass: HomeAssistant, str: string, context?: object): string | boolean;
+export declare function renderTemplate(hass: HomeAssistant, str: string, context?: object, validate?: boolean): string | boolean;
+/**
+ * Test if the input contains a valid template
+ * @param {any} str the variable to check
+ * @returns if the input is a string that contains a template
+ */
+export declare function hasTemplate(str: any): boolean;

package/dist/index.js

@@ -5,49 +5,72 @@ import { addTests } from './tests';
 import { fetchLabelRegistry } from './utils/labels';
 import { buildStatesObject } from './utils/states';
 if (!window.haNunjucks) {
-    window.haNunjucks = {};
+    window.haNunjucks = {
+        states: {},
+        labelRegistry: {},
+    };
+    // Async setup label registry and states object on import
+    const registrySetup = async () => {
+        const ha = document.querySelector('home-assistant');
+        if (!ha ||
+            !ha.hass ||
+            !ha.hass.connected ||
+            !ha.hass.connection ||
+            !ha.hass.connection.connected) {
+            setTimeout(registrySetup, 10);
+            return;
+        }
+        // Number and datetime translators
+        window.haNunjucks.numberFormat = new Intl.NumberFormat(ha.hass.language);
+        window.haNunjucks.dateFormat = new Intl.DateTimeFormat(ha.hass.language, { dateStyle: 'full' });
+        window.haNunjucks.timeFormat = new Intl.DateTimeFormat(ha.hass.language, { timeStyle: 'long' });
+        window.haNunjucks.datetimeFormat = new Intl.DateTimeFormat(ha.hass.language, { dateStyle: 'full', timeStyle: 'long' });
+        // Label registry and states object
+        window.haNunjucks.hass = ha.hass;
+        fetchLabelRegistry();
+        buildStatesObject();
+    };
+    registrySetup();
+    // Initialize global ha-nunjucks environment
     nunjucks.installJinjaCompat();
     window.haNunjucks.env = addTests(addFilters(addGlobals(new nunjucks.Environment())));
-    window.haNunjucks.states = {};
-    window.hassConnection?.then((hassConnection) => {
-        const entities = hassConnection?.conn?._entityRegistryDisplay?.state
-            ?.entities;
-        for (const entity of entities) {
-            const [domain, _id] = entity.ei.split('.');
-            window.haNunjucks.states[domain] ??= {};
-        }
-    });
 }
 /**
  * Render a Home Assistant template string using nunjucks
  * @param {HomeAssistant} hass The Home Assistant object
  * @param {string} str The template string to render
  * @param {object} [context] Additional context to expose to nunjucks
+ * @param {boolean} [validate=true] Validate that the input contains a template.
  * @returns {string | boolean} The rendered template string if a string was provided, otherwise the unaltered input
  */
-export function renderTemplate(hass, str, context) {
-    if (!window.haNunjucks?.labelRegistry) {
-        fetchLabelRegistry(hass);
+export function renderTemplate(hass, str, context, validate = true) {
+    if (validate && !hasTemplate(str)) {
+        return str;
     }
     window.haNunjucks.hass = hass;
-    if (typeof str == 'string' &&
-        ((str.includes('{{') && str.includes('}}')) ||
-            (str.includes('{%') && str.includes('%}')))) {
-        str = window.haNunjucks.env
-            .renderString(structuredClone(str), {
-            hass,
-            _states: buildStatesObject(),
-            ...context,
-        })
-            .trim();
-        if ([undefined, null, 'undefined', 'null', 'None'].includes(str)) {
-            return '';
-        }
-        const lowerStr = str.toLowerCase();
-        if (['true', 'false'].includes(lowerStr)) {
-            return lowerStr == 'true';
-        }
-        return str;
+    buildStatesObject();
+    str = window.haNunjucks.env
+        .renderString(structuredClone(str), {
+        hass,
+        _states: window.haNunjucks.states,
+        ...context,
+    })
+        .trim();
+    if ([undefined, null, 'undefined', 'null', 'None'].includes(str)) {
+        return '';
+    }
+    const lowerStr = str.toLowerCase();
+    if (['true', 'false'].includes(lowerStr)) {
+        return lowerStr == 'true';
     }
     return str;
 }
+const hasTemplateRegex = /{{.*?}}|{%.*?%}/;
+/**
+ * Test if the input contains a valid template
+ * @param {any} str the variable to check
+ * @returns if the input is a string that contains a template
+ */
+export function hasTemplate(str) {
+    return hasTemplateRegex.test(str);
+}

package/dist/models/interfaces/hass.d.ts

@@ -37,3 +37,6 @@ export interface HomeAssistant {
     formatEntityAttributeValue(stateObj: HassEntity, attribute: string, value?: any): string;
     formatEntityAttributeName(stateObj: HassEntity, attribute: string): string;
 }
+export interface HassElement extends HTMLElement {
+    hass: HomeAssistant;
+}

package/dist/utils/labels.d.ts

@@ -1,5 +1,5 @@
 import { HomeAssistant } from '../models/interfaces/hass';
-export declare function fetchLabelRegistry(hass: HomeAssistant): Promise<void>;
+export declare function fetchLabelRegistry(): Promise<void>;
 export declare function labels(hass: HomeAssistant, lookup_value?: string): string[];
 export declare function label_id(lookup_value: string): string | undefined;
 export declare function label_name(lookup_value: string): string;

package/dist/utils/labels.js

@@ -1,13 +1,10 @@
-export async function fetchLabelRegistry(hass) {
-    if (hass.connection) {
-        window.haNunjucks.labelRegistry = {};
-        const labels = await hass.connection.sendMessagePromise({
-            type: 'config/label_registry/list',
-        });
-        labels.sort((ent1, ent2) => ent1.name.localeCompare(ent2.name));
-        for (const label of labels) {
-            window.haNunjucks.labelRegistry[label.label_id] = label;
-        }
+export async function fetchLabelRegistry() {
+    const labels = await window.haNunjucks.hass.connection.sendMessagePromise({
+        type: 'config/label_registry/list',
+    });
+    labels.sort((ent1, ent2) => ent1.name.localeCompare(ent2.name));
+    for (const label of labels) {
+        window.haNunjucks.labelRegistry[label.label_id] = label;
     }
 }
 export function labels(hass, lookup_value) {

package/dist/utils/state_translated.d.ts

@@ -1,4 +1,9 @@
+import { date, datetime, time } from 'ts-py-datetime';
 import { HomeAssistant } from '../models/interfaces/hass';
 export declare function state_translated(hass: HomeAssistant, entity_id: string, state?: string): string;
 export declare function attr_name_translated(hass: HomeAssistant, entity_id: string, attr_name: string): string;
 export declare function attr_value_translated(hass: HomeAssistant, entity_id: string, attr_name: string, attr_value?: string): any;
+export declare function number_translated(value: number): string | number;
+export declare function date_translated(value: date | datetime): string | date | datetime;
+export declare function time_translated(value: time | datetime): string | datetime | time;
+export declare function datetime_translated(value: datetime): string | datetime;

package/dist/utils/state_translated.js

@@ -26,3 +26,33 @@ export function attr_value_translated(hass, entity_id, attr_name, attr_value) {
             undefined);
     }
 }
+export function number_translated(value) {
+    if (isNaN(value)) {
+        return value;
+    }
+    return window.haNunjucks.numberFormat.format(value);
+}
+export function date_translated(value) {
+    try {
+        return window.haNunjucks.dateFormat.format(value.jsDate);
+    }
+    catch {
+        return value;
+    }
+}
+export function time_translated(value) {
+    try {
+        return window.haNunjucks.timeFormat.format(value.jsDate);
+    }
+    catch {
+        return value;
+    }
+}
+export function datetime_translated(value) {
+    try {
+        return window.haNunjucks.datetimeFormat.format(value.jsDate);
+    }
+    catch {
+        return value;
+    }
+}

package/dist/utils/states.d.ts

@@ -1,7 +1,7 @@
 import { HomeAssistant } from '../models/interfaces/hass';
+export declare function buildStatesObject(): void;
 export declare function states(hass: HomeAssistant, entity_id: string, rounded?: boolean | Record<string, boolean>, with_unit?: boolean): string | undefined;
 export declare function is_state(hass: HomeAssistant, entity_id: string, value: string | string[]): boolean;
 export declare function state_attr(hass: HomeAssistant, entity_id: string, attribute: string): any;
 export declare function is_state_attr(hass: HomeAssistant, entity_id: string, attribute: string, value: string): boolean;
 export declare function has_value(hass: HomeAssistant, entity_id: string): boolean;
-export declare function buildStatesObject(): Record<string, Record<string, import("home-assistant-js-websocket").HassEntity>>;

package/dist/utils/states.js

@@ -1,3 +1,11 @@
+export function buildStatesObject() {
+    for (const entityId in window.haNunjucks.hass.states) {
+        const [domain, id] = entityId.split('.');
+        window.haNunjucks.states[domain] ??= {};
+        window.haNunjucks.states[domain][id] =
+            window.haNunjucks.hass.states[entityId];
+    }
+}
 export function states(hass, entity_id, rounded, with_unit) {
     if (typeof rounded == 'object' && !Array.isArray(rounded)) {
         with_unit = rounded.with_unit ?? with_unit;
@@ -64,12 +72,3 @@ export function has_value(hass, entity_id) {
         return false;
     }
 }
-export function buildStatesObject() {
-    for (const entityId in window.haNunjucks.hass.states) {
-        const [domain, id] = entityId.split('.');
-        window.haNunjucks.states[domain] ??= {};
-        window.haNunjucks.states[domain][id] =
-            window.haNunjucks.hass.states[entityId];
-    }
-    return window.haNunjucks.states;
-}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "ha-nunjucks",
-	"version": "1.4.0",
+	"version": "1.5.0",
 	"description": "Wrapper for nunjucks for use with Home Assistant frontend custom components to render templates",
 	"main": "./dist/index.js",
 	"files": [
@@ -8,7 +8,7 @@
 	],
 	"type": "module",
 	"scripts": {
-		"test": "ts-mocha tests/**/*.test.ts",
+		"test": "ts-mocha tests/**/*.test.ts --require fixtures.cjs",
 		"build": "tsc",
 		"prelint": "tsc --noemit",
 		"lint": "eslint --config ./.eslintrc.config.cjs"