ha-nunjucks 1.4.0 → 1.6.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)
 
@@ -136,15 +168,17 @@ Functions used to determine an entity's state or an attribute.
 | device_attr     | function, filter | device_or_entity_id, attr_name             | Returns the value of attr_name for the given device or entity ID.                            |
 | is_device_attr  | function         | device_or_entity_id, attr_name, attr_value | Returns whether the value of attr_name for the given device or entity ID matches attr_value. |
 | device_id       | function, filter | entity_id                                  | Returns the device ID for a given entity ID or device name.                                  |
+| device_name     | function, filter | device_or_entity_id                        | Returns the device name as defined by user or default for a give entity or device ID.        |
 
 ### [Floors](https://www.home-assistant.io/docs/configuration/templating/#floors)
 
-| Name        | Type             | Arguments        | Description                                                                               |
-| ----------- | ---------------- | ---------------- | ----------------------------------------------------------------------------------------- |
-| floors      | function         |                  | Returns the full list of floor IDs that include an area.                                  |
-| floor_id    | function, filter | lookup_value     | Returns the floor ID for a given device ID, entity ID, area ID, or area name.             |
-| floor_name  | function, filter | lookup_value     | Returns the floor name for a given device ID, entity ID, area ID, area name, or floor ID. |
-| floor_areas | function, filter | floor_name_or_id | Returns the list of area IDs tied to a given floor ID or name.                            |
+| Name           | Type             | Arguments        | Description                                                                                                 |
+| -------------- | ---------------- | ---------------- | ----------------------------------------------------------------------------------------------------------- |
+| floors         | function         |                  | Returns the full list of floor IDs that include an area.                                                    |
+| floor_id       | function, filter | lookup_value     | Returns the floor ID for a given floor name or alias, device ID, entity ID, area ID, or area name or alias. |
+| floor_name     | function, filter | lookup_value     | Returns the floor name for a given device ID, entity ID, area ID, area name, or floor ID.                   |
+| floor_areas    | function, filter | floor_name_or_id | Returns the list of area IDs tied to a given floor ID or name.                                              |
+| floor_entities | function, filter | floor_name_or_id | Returns the list of entity IDs tied to a given floor ID or name.                                            |
 
 ### [Areas](https://www.home-assistant.io/docs/configuration/templating/#areas)
 
@@ -164,16 +198,17 @@ 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                                                                                |
-| -------------- | ---------------- | ----------------------- | ------------------------------------------------------------------------------------------ |
-| labels         | function, filter | lookup_value (optional) | Returns the full list of label IDs, or those for a given area ID, device ID, or entity ID. |
-| label_id       | function, filter | lookup_value            | Returns the label ID for a given label name.                                               |
-| label_name     | function, filter | lookup_value            | Returns the label name for a given label ID.                                               |
-| label_areas    | function, filter | label_name_or_id        | Returns the list of area IDs tied to a given label ID or name.                             |
-| label_devices  | function, filter | label_name_or_id        | Returns the list of device IDs tied to a given label ID or name.                           |
-| label_entities | function, filter | label_name_or_id        | Returns the list of entity IDs tied to a given label ID or name.                           |
+| Name              | Type             | Arguments               | Description                                                                                |
+| ----------------- | ---------------- | ----------------------- | ------------------------------------------------------------------------------------------ |
+| labels            | function, filter | lookup_value (optional) | Returns the full list of label IDs, or those for a given area ID, device ID, or entity ID. |
+| label_id          | function, filter | lookup_value            | Returns the label ID for a given label name.                                               |
+| label_name        | function, filter | lookup_value            | Returns the label name for a given label ID.                                               |
+| label_description | function, filter | lookup_value            | Returns the label description for a given label ID.                                        |
+| label_areas       | function, filter | label_name_or_id        | Returns the list of area IDs tied to a given label ID or name.                             |
+| label_devices     | function, filter | label_name_or_id        | Returns the list of device IDs tied to a given label ID or name.                           |
+| label_entities    | function, filter | label_name_or_id        | Returns the list of entity IDs tied to a given label ID or name.                           |
 
 ### [Immediate If](https://www.home-assistant.io/docs/configuration/templating/#immediate-if-iif)
 
@@ -191,21 +226,22 @@ A shorthand for an if else statement.
 - JS Date is not as good at handling timezones as Python datetime. Be careful about timezone differences! You can try to account for this using the `utc` flags and/or by including a timezone offset in a datetime string to parse using `as_datetime` or `strptime`.
 - Including time extensions in your templates does not cause them to refresh more regularly by themselves, although they will still update whenever the `hass` object does. If you are a developer, you have to implement this behavior yourself in your custom cards.
 
-| Name             | Type             | Arguments                                                | Description                                                                                                                                                                                                                                                                                                                                                                                        |
-| ---------------- | ---------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| now              | function         |                                                          | Returns a datetime object that represents the current time in your time zone.                                                                                                                                                                                                                                                                                                                      |
-| utcnow           | function         |                                                          | Returns a datetime object of the current time in the UTC timezone.                                                                                                                                                                                                                                                                                                                                 |
-| today_at         | function, filter | value                                                    | Converts a string containing a military time format to a datetime object with today’s date in your time zone. Defaults to midnight (00:00).                                                                                                                                                                                                                                                        |
-| as_datetime      | function, filter | value, fallback (optional), utc (default true)           | Converts a string containing a timestamp, or valid UNIX timestamp, to a datetime object. If that fails, it returns the fallback value or, if omitted, raises an error. When the input is already a datetime object it will be returned as is. in case the input is a datetime.date object, midnight will be added as time.                                                                         |
-| as_timestamp     | function, filter | value, fallback (optional)                               | Converts a datetime object or string to UNIX timestamp. If that fails, returns the fallback value, or if omitted raises an error.                                                                                                                                                                                                                                                                  |
-| as_local         | function, filter | value                                                    | Converts a datetime object to local time.                                                                                                                                                                                                                                                                                                                                                          |
-| strptime         | function         | value, format, fallback (optional), utc (default false)  | Parses a string based on a [format](https://d3js.org/d3-time-format#locale_format) and returns a datetime object. If that fails, it returns the default value or, if omitted, raises an error.                                                                                                                                                                                                     |
-| time_since       | function, filter | value, precision (default 1)                             | Returns a human readable string indicating the difference between now and an input past datetime object. `precision` indicates how many units (years, months, days, hours, minutes, seconds) to use, with the last unit being rounded and 0 being the same as 6. If the input datetime is in the past it returns the input. If the input datetime is not a datetime object it returns nothing.     |
-| time_until       | function, filter | value, precision (default 1)                             | Returns a human readable string indicating the difference between now and an input future datetime object. `precision` indicates how many units (years, months, days, hours, minutes, seconds) to use, with the last unit being rounded and 0 being the same as 6. If the input datetime is in the future it returns the input. If the input datetime is not a datetime object it returns nothing. |
-| as_timedelta     | function, filter | value                                                    | Converts a string to a timedelta object. Expects data in the format `DD HH:MM:SS.uuuuuu`, `DD HH:MM:SS,uuuuuu`, or as specified by ISO 8601 (e.g. `P4DT1H15M20S` which is equivalent to `4 1:15:20`) or PostgreSQL’s day-time interval format (e.g. `3 days 04:05:06`).                                                                                                                            |
-| timestamp_local  | filter           | value, fallback (optional)                               | Converts a UNIX timestamp to the ISO format string representation as date/time in your local timezone. If that fails, returns the `fallback` value, or if omitted raises an error.                                                                                                                                                                                                                 |
-| timestamp_utc    | filter           | value, fallback (optional)                               | Converts a UNIX timestamp to the ISO format string representation as date/time in UTC timezone. If that fails, returns the `fallback` value, or if omitted raises an error.                                                                                                                                                                                                                        |
-| timestamp_custom | filter           | value, format, local (default true), fallback (optional) | Converts a UNIX timestamp to its string representation based on a custom format. Uses the local timezone by default. If that fails, returns the `fallback` value, or if omitted raises an error.                                                                                                                                                                                                   |
+| Name             | Type             | Arguments                                                | Description                                                                                                                                                                                                                                                                                                                                                                                      |
+| ---------------- | ---------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| now              | function         |                                                          | Returns a datetime object that represents the current time in your time zone.                                                                                                                                                                                                                                                                                                                    |
+| utcnow           | function         |                                                          | Returns a datetime object of the current time in the UTC timezone.                                                                                                                                                                                                                                                                                                                               |
+| today_at         | function, filter | value                                                    | Converts a string containing a military time format to a datetime object with today’s date in your time zone. Defaults to midnight (00:00).                                                                                                                                                                                                                                                      |
+| as_datetime      | function, filter | value, fallback (optional), utc (default true)           | Converts a string containing a timestamp, or valid UNIX timestamp, to a datetime object. If that fails, it returns the fallback value or, if omitted, raises an error. When the input is already a datetime object it will be returned as is. in case the input is a datetime.date object, midnight will be added as time.                                                                       |
+| as_timestamp     | function, filter | value, fallback (optional)                               | Converts a datetime object or string to UNIX timestamp. If that fails, returns the fallback value, or if omitted raises an error.                                                                                                                                                                                                                                                                |
+| as_local         | function, filter | value                                                    | Converts a datetime object to local time.                                                                                                                                                                                                                                                                                                                                                        |
+| strptime         | function         | value, format, fallback (optional), utc (default false)  | Parses a string based on a [format](https://d3js.org/d3-time-format#locale_format) and returns a datetime object. If that fails, it returns the default value or, if omitted, raises an error.                                                                                                                                                                                                   |
+| relative_time    | function, filter | value                                                    | Returns a human readable string indicating the differenceb between now and an input past datetime object. Only uses the largest unit (years, months, days, hours, minutes, seconds) rounded.                                                                                                                                                                                                     |
+| time_since       | function, filter | value, precision (default 1)                             | Returns a human readable string indicating the difference between now and an input past datetime object. `precision` indicates how many units (years, months, days, hours, minutes, seconds) to use, with the last unit being rounded and 0 being the same as 6. If the input datetime is in the future it returns the input. If the input datetime is not a datetime object it returns nothing. |
+| time_until       | function, filter | value, precision (default 1)                             | Returns a human readable string indicating the difference between now and an input future datetime object. `precision` indicates how many units (years, months, days, hours, minutes, seconds) to use, with the last unit being rounded and 0 being the same as 6. If the input datetime is in the past it returns the input. If the input datetime is not a datetime object it returns nothing. |
+| as_timedelta     | function, filter | value                                                    | Converts a string to a timedelta object. Expects data in the format `DD HH:MM:SS.uuuuuu`, `DD HH:MM:SS,uuuuuu`, or as specified by ISO 8601 (e.g. `P4DT1H15M20S` which is equivalent to `4 1:15:20`) or PostgreSQL’s day-time interval format (e.g. `3 days 04:05:06`).                                                                                                                          |
+| timestamp_local  | filter           | value, fallback (optional)                               | Converts a UNIX timestamp to the ISO format string representation as date/time in your local timezone. If that fails, returns the `fallback` value, or if omitted raises an error.                                                                                                                                                                                                               |
+| timestamp_utc    | filter           | value, fallback (optional)                               | Converts a UNIX timestamp to the ISO format string representation as date/time in UTC timezone. If that fails, returns the `fallback` value, or if omitted raises an error.                                                                                                                                                                                                                      |
+| timestamp_custom | filter           | value, format, local (default true), fallback (optional) | Converts a UNIX timestamp to its string representation based on a custom format. Uses the local timezone by default. If that fails, returns the `fallback` value, or if omitted raises an error.                                                                                                                                                                                                 |
 
 In addition to these functions, you have access to [a datetime library](https://github.com/Nerwyn/ts-py-datetime) which emulates the Python datetime module in TypeScript. You can instantiate `date`, `time`, `datetime`, and `timedelta` objects using the `dt` object. You can then access it's class methods using these objects. To use the static method and constants of these classes, you can reference them directly without prefixing them with `dt`. See the README in the datetime repository linked above for more information on how to use it.
 
@@ -228,6 +264,12 @@ In addition to these functions, you have access to [a datetime library](https://
 | to_json   | filter | obj, ensure_ascii, pretty_print, sort_keys | Turn an object into a JSON string. `ensure_ascii` converts unicode characters into escape sequences. `pretty_print` formats the output with new lines and an indent of two spaces. `sort_keys` sorts the keys of the JSON object. **Consider using the nunjucks `safe` filter with this, or the nunjucks `dump` filter instead.** |
 | from_json | filter | value                                      | Parse a string as JSON.                                                                                                                                                                                                                                                                                                           |
 
+### [Is Defined](https://www.home-assistant.io/docs/configuration/templating/#is-defined)
+
+| Name       | Type   | Arguments | Description                                                    |
+| ---------- | ------ | --------- | -------------------------------------------------------------- |
+| is_defined | filter | value     | Returns the value if it is defined, otherwise throws an error. |
+
 ### [Distance](https://www.home-assistant.io/docs/configuration/templating/#distance)
 
 | Name     | Type             | Arguments | Description                                                                                                                                                                        |
@@ -287,10 +329,11 @@ In addition to these functions, you have access to [a datetime library](https://
 
 ### [Type Conversions](https://www.home-assistant.io/docs/configuration/templating/#type-conversions)
 
-| Name | Type     | Arguments | Description                                            |
-| ---- | -------- | --------- | ------------------------------------------------------ |
-| set  | function | args      | Convert a list/array to a set. Removes duplicates.     |
-| list | function | args      | Convert a set to an array. Does not remove duplicates. |
+| Name | Type             | Arguments | Description                                            |
+| ---- | ---------------- | --------- | ------------------------------------------------------ |
+| set  | function         | args      | Convert a list/array to a set. Removes duplicates.     |
+| list | function         | args      | Convert a set to an array. Does not remove duplicates. |
+| str  | function, filter | value     | Return the string representation of the input.         |
 
 ### [Iterating Multiple Objects](https://www.home-assistant.io/docs/configuration/templating/#iterating-multiple-objects)
 
@@ -298,6 +341,16 @@ In addition to these functions, you have access to [a datetime library](https://
 | ---- | -------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------- |
 | zip  | function | args      | Use to iterate over multiple collections in one operation. If given one array will perform the opposite action and unzip the list. |
 
+### [String filters](https://www.home-assistant.io/docs/configuration/templating/#string-filters)
+
+| Name          | Type   | Arguments                     | Description                                                                                              |
+| ------------- | ------ | ----------------------------- | -------------------------------------------------------------------------------------------------------- |
+| urlencode     | filter | value                         | Convert an object to a percent-encoded ASCII text string.                                                |
+| slugify       | filter | value, separator (default \_) | Convert a given string into a "slug".                                                                    |
+| ordinal       | filter | value                         | Convert an integer into a number defining a position in a series (e.g. `1st`, `2nd`, `3rd`, `4th`, etc). |
+| base64_encode | filter | value                         | Encodes a string or bytes to a base 64 string.                                                           |
+| base64_decode | filter | value                         | Decodes a base 64 string to a UTF-8 string.                                                              |
+
 ### [Regular Expressions](https://www.home-assistant.io/docs/configuration/templating/#regular-expressions)
 
 **NOTE**: The format of regular expressions in nunjucks is different than jinja2. You may want to read the [Nunjucks](https://mozilla.github.io/nunjucks/templating.html#regular-expressions) and [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions) documentation.
@@ -315,10 +368,9 @@ In addition to these functions, you have access to [a datetime library](https://
 
 Functions that are not from the Home Assistant templating documentation.
 
-| Name        | Type             | Arguments | Description                                                                                                                                           |
-| ----------- | ---------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| match_media | function         | value     | Returns the boolean result of the provided [CSS media query](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries). |
-| str         | function, filter | value     | Return the string representation of the input.                                                                                                        |
+| Name        | Type     | Arguments | Description                                                                                                                                           |
+| ----------- | -------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| match_media | function | value     | Returns the boolean result of the provided [CSS media query](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries). |
 
 [last-commit-shield]: https://img.shields.io/github/last-commit/Nerwyn/ha-nunjucks?style=for-the-badge
 [commits]: https://github.com/Nerwyn/ha-nunjucks/commits/main

package/dist/filters.js

@@ -1,18 +1,19 @@
 import { area_devices, area_entities, area_id, area_name } from './utils/areas';
 import { contains } from './utils/contains';
-import { device_attr, device_entities, device_id } from './utils/devices';
+import { device_attr, device_entities, device_id, device_name, } from './utils/devices';
 import { closest } from './utils/distance';
-import { floor_areas, floor_id, floor_name } from './utils/floors';
+import { floor_areas, floor_entities, floor_id, floor_name, } from './utils/floors';
 import { expand } from './utils/groups';
 import { iif } from './utils/iif';
-import { from_json, to_json } from './utils/json';
-import { label_areas, label_devices, label_entities, label_id, label_name, labels, } from './utils/labels';
+import { from_json, is_defined, to_json } from './utils/json';
+import { label_areas, label_description, label_devices, label_entities, label_id, label_name, labels, } from './utils/labels';
 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';
+import { base64_decode, base64_encode, ordinal, slugify, } from './utils/string_filters';
+import { as_datetime, as_local, as_timedelta, as_timestamp, relative_time, time_since, time_until, timestamp_custom, timestamp_local, timestamp_utc, today_at, } from './utils/time';
 export function addFilters(env) {
     for (const func in FILTERS) {
         env.addFilter(func, function (...args) {
@@ -41,10 +42,12 @@ const HASS_FILTERS = {
     device_entities,
     device_attr,
     device_id,
+    device_name,
     // Floors
     floor_id,
     floor_name,
     floor_areas,
+    floor_entities,
     // Areas
     area_id,
     area_name,
@@ -64,19 +67,27 @@ const FILTERS = {
     // Labels
     label_id,
     label_name,
+    label_description,
     // Time
     today_at,
+    as_timedelta,
     as_datetime,
     as_timestamp,
     as_local,
+    relative_time,
     time_since,
     time_until,
     timestamp_local,
     timestamp_utc,
     timestamp_custom,
+    date_translated,
+    time_translated,
+    datetime_translated,
     // To/From JSON
     to_json,
     from_json,
+    // Is Defined
+    is_defined,
     // Distance
     closest,
     // Contains
@@ -107,10 +118,17 @@ const FILTERS = {
     ord,
     multiply,
     add,
+    number_translated,
+    // Type conversions
+    str,
+    // String filters
+    // urlencode filter is built into nunjucks
+    slugify,
+    ordinal,
+    base64_encode,
+    base64_decode,
     // Regular Expressions
     regex_replace,
     regex_findall,
     regex_findall_index,
-    // Miscellaneous
-    str,
 };

package/dist/globals.js

@@ -1,17 +1,18 @@
 import { area_devices, area_entities, area_id, area_name, areas, } from './utils/areas';
-import { device_attr, device_entities, device_id, is_device_attr, } from './utils/devices';
+import { device_attr, device_entities, device_id, device_name, is_device_attr, } from './utils/devices';
 import { closest, distance } from './utils/distance';
 import { is_hidden_entity } from './utils/entities';
-import { floor_areas, floor_id, floor_name, floors } from './utils/floors';
+import { floor_areas, floor_entities, floor_id, floor_name, floors, } from './utils/floors';
 import { expand } from './utils/groups';
 import { iif } from './utils/iif';
 import { integration_entities } from './utils/integrations';
-import { label_areas, label_devices, label_entities, label_id, label_name, labels, } from './utils/labels';
+import { label_areas, label_description, 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 { slugify } from './utils/string_filters';
+import { as_datetime, as_local, as_timedelta, as_timestamp, now, relative_time, strptime, time_since, time_until, today_at, utcnow, } from './utils/time';
 import { list, set } from './utils/type_conversions';
 import { zip } from './utils/zip';
 import dt, { date, datetime, time, timedelta } from 'ts-py-datetime';
@@ -56,11 +57,13 @@ const HASS_GLOBALS = {
     device_attr,
     is_device_attr,
     device_id,
+    device_name,
     // Floors
     floors,
     floor_id,
     floor_name,
     floor_areas,
+    floor_entities,
     // Areas
     areas,
     area_id,
@@ -84,6 +87,7 @@ const GLOBALS = {
     // Labels
     label_id,
     label_name,
+    label_description,
     // Time
     now,
     utcnow,
@@ -92,9 +96,13 @@ const GLOBALS = {
     as_timestamp,
     as_local,
     strptime,
+    relative_time,
     time_since,
     time_until,
     as_timedelta,
+    date_translated,
+    time_translated,
+    datetime_translated,
     // Numeric,
     float,
     is_number,
@@ -114,14 +122,17 @@ const GLOBALS = {
     average,
     median,
     statistical_mode,
+    number_translated,
     // Type Conversions
     set,
     list,
+    str,
     // Iterating Multiple Objects
     zip,
+    // String fitlers
+    slugify,
     // Miscellaneous
     match_media,
-    str,
 };
 const CONST_GLOBALS = {
     e,

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,74 @@ 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' });
+        window.haNunjucks.ordinalFormat = new Intl.PluralRules('en-US', // ha.hass.language, // Use english for proper numeric suffixes
+        { type: 'ordinal' });
+        // 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/areas.js

@@ -20,7 +20,8 @@ export function area_id(hass, lookup_value) {
                 return hass.devices[lookup_value].area_id;
             }
             for (const areaId in hass.areas) {
-                if (hass.areas[areaId].name == lookup_value) {
+                if (hass.areas[areaId].name == lookup_value ||
+                    hass.areas[areaId].aliases?.includes(lookup_value)) {
                     return areaId;
                 }
             }
@@ -57,12 +58,15 @@ export function area_entities(hass, area_name_or_id) {
     try {
         const entityIds = [];
         if (area_name_or_id) {
+            let areaId = area_name_or_id;
+            if (!hass.areas[area_name_or_id]) {
+                areaId = area_id(hass, area_name_or_id) ?? area_name_or_id;
+            }
             const deviceIds = area_devices(hass, area_name_or_id);
-            for (const deviceId of deviceIds) {
-                for (const entityId in hass.entities) {
-                    if (hass.entities[entityId].device_id == deviceId) {
-                        entityIds.push(entityId);
-                    }
+            for (const entityId in hass.entities) {
+                if (deviceIds.includes(hass.entities[entityId].device_id) ||
+                    hass.entities[entityId].area_id == areaId) {
+                    entityIds.push(entityId);
                 }
             }
             entityIds.sort();
@@ -79,7 +83,8 @@ export function area_devices(hass, area_name_or_id) {
         if (area_name_or_id) {
             if (!(area_name_or_id in hass.areas)) {
                 for (const areaId in hass.areas) {
-                    if (hass.areas[areaId].name == area_name_or_id) {
+                    if (hass.areas[areaId].name == area_name_or_id ||
+                        hass.areas[areaId].aliases?.includes(area_name_or_id)) {
                         area_name_or_id = areaId;
                         break;
                     }

package/dist/utils/devices.d.ts

@@ -4,3 +4,4 @@ export declare function device_entities(hass: HomeAssistant, device_id: string):
 export declare function device_attr(hass: HomeAssistant, device_or_entity_id: string, attr_name: keyof DeviceRegistryEntry): any;
 export declare function is_device_attr(hass: HomeAssistant, device_or_entity_id: string, attr_name: keyof DeviceRegistryEntry, attr_value: string): boolean;
 export declare function device_id(hass: HomeAssistant, entity_id: string): string | undefined;
+export declare function device_name(hass: HomeAssistant, lookup_value: string): string | null | undefined;

package/dist/utils/devices.js

@@ -55,3 +55,18 @@ export function device_id(hass, entity_id) {
         return undefined;
     }
 }
+export function device_name(hass, lookup_value) {
+    try {
+        if (hass.entities[lookup_value]) {
+            lookup_value = hass.entities[lookup_value].device_id;
+        }
+        const device = hass.devices[lookup_value];
+        if (device) {
+            return device.name_by_user ?? device.name;
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/utils/floors.d.ts

@@ -3,3 +3,4 @@ export declare function floors(hass: HomeAssistant): string[];
 export declare function floor_id(hass: HomeAssistant, lookup_value: string): string | null | undefined;
 export declare function floor_name(hass: HomeAssistant, lookup_value: string): string | undefined;
 export declare function floor_areas(hass: HomeAssistant, floor_name_or_id: string): string[];
+export declare function floor_entities(hass: HomeAssistant, floor_name_or_id: string): string[];

package/dist/utils/floors.js

@@ -4,25 +4,37 @@ export function floors(hass) {
 export function floor_id(hass, lookup_value) {
     try {
         let areaId = lookup_value;
+        // Entity ID
         if (hass.entities[lookup_value]) {
             areaId = hass.entities[lookup_value].area_id ?? areaId;
             lookup_value =
                 hass.entities[lookup_value].device_id ?? lookup_value;
         }
         if (lookup_value) {
+            // Device ID
             if (hass.devices[lookup_value]) {
                 areaId = hass.devices[lookup_value].area_id ?? areaId;
             }
+            // Area ID
             if (hass.areas[areaId]) {
                 return hass.areas[areaId].floor_id;
             }
             else {
+                // Area name or alias
                 for (const areaId in hass.areas) {
-                    if (hass.areas[areaId].name == lookup_value) {
+                    if (hass.areas[areaId].name == lookup_value ||
+                        hass.areas[areaId].aliases?.includes(lookup_value)) {
                         return hass.areas[areaId].floor_id;
                     }
                 }
             }
+            // Floor name or alias
+            for (const floorId in hass.floors) {
+                if (hass.floors[floorId].name == lookup_value ||
+                    hass.floors[floorId].aliases?.includes(lookup_value)) {
+                    return floorId;
+                }
+            }
         }
         return undefined;
     }
@@ -50,7 +62,8 @@ export function floor_areas(hass, floor_name_or_id) {
             }
             else {
                 for (const id in hass.floors) {
-                    if (hass.floors[id].name == floor_name_or_id) {
+                    if (hass.floors[id].name == floor_name_or_id ||
+                        hass.floors[id].aliases?.includes(floor_name_or_id)) {
                         floorId = id;
                         break;
                     }
@@ -71,3 +84,22 @@ export function floor_areas(hass, floor_name_or_id) {
         return [];
     }
 }
+export function floor_entities(hass, floor_name_or_id) {
+    try {
+        const res = new Set();
+        const areas = floor_areas(hass, floor_name_or_id);
+        for (const entityId in hass.entities) {
+            if (areas.includes(hass.entities[entityId].area_id)) {
+                res.add(entityId);
+                for (const subEntityId of hass.states[entityId]?.attributes
+                    ?.entity_id ?? []) {
+                    res.add(subEntityId);
+                }
+            }
+        }
+        return Array.from(res);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/utils/json.d.ts

@@ -1,2 +1,3 @@
 export declare function to_json(obj: object, ensure_ascii?: boolean | Record<string, boolean>, pretty_print?: boolean, sort_keys?: boolean): string;
 export declare function from_json(value: string): any;
+export declare function is_defined(value: any): any;

package/dist/utils/json.js

@@ -21,3 +21,9 @@ export function to_json(obj, ensure_ascii = false, pretty_print = false, sort_ke
 export function from_json(value) {
     return JSON.parse(value);
 }
+export function is_defined(value) {
+    if (value == undefined) {
+        throw Error('UndefinedError: input is undefined');
+    }
+    return value;
+}

package/dist/utils/labels.d.ts

@@ -1,8 +1,9 @@
 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;
+export declare function label_description(lookup_value: string): string | undefined;
 export declare function label_areas(hass: HomeAssistant, label_name_or_id: string): string[];
 export declare function label_devices(hass: HomeAssistant, label_name_or_id: string): string[];
 export declare function label_entities(hass: HomeAssistant, label_name_or_id: 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) {
@@ -35,6 +32,9 @@ export function label_id(lookup_value) {
 export function label_name(lookup_value) {
     return window.haNunjucks.labelRegistry[lookup_value]?.name;
 }
+export function label_description(lookup_value) {
+    return window.haNunjucks.labelRegistry[lookup_value]?.description;
+}
 export function label_areas(hass, label_name_or_id) {
     try {
         const areaIds = [];

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, precision?: 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,40 @@ export function attr_value_translated(hass, entity_id, attr_name, attr_value) {
             undefined);
     }
 }
+export function number_translated(value, precision) {
+    value = Number(value);
+    if (isNaN(value)) {
+        return value;
+    }
+    if (precision) {
+        return value.toLocaleString(window.haNunjucks.hass.language, {
+            minimumFractionDigits: precision,
+            maximumFractionDigits: precision,
+        });
+    }
+    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/dist/utils/string_filters.d.ts

@@ -0,0 +1,4 @@
+export declare function slugify(str: string, separator?: string): string;
+export declare function ordinal(num: number): string;
+export declare function base64_encode(value: string): string;
+export declare function base64_decode(value: string): string;

package/dist/utils/string_filters.js

@@ -0,0 +1,27 @@
+import slugifyLib from 'slugify';
+export function slugify(str, separator = '_') {
+    return slugifyLib(str, {
+        replacement: separator,
+        lower: true,
+        strict: true,
+    });
+}
+export function ordinal(num) {
+    if (isNaN(num)) {
+        throw Error('Input must be a number');
+    }
+    const suffixes = {
+        one: 'st',
+        two: 'nd',
+        few: 'rd',
+        other: 'th',
+    };
+    const suffix = suffixes[window.haNunjucks.ordinalFormat.select(num)] || 'th';
+    return `${num}${suffix}`;
+}
+export function base64_encode(value) {
+    return btoa(value);
+}
+export function base64_decode(value) {
+    return atob(value);
+}

package/dist/utils/time.d.ts

@@ -6,6 +6,7 @@ export declare function as_datetime(value: number | string | datetime | date, fa
 export declare function as_timestamp(value: number | string | datetime | date, fallback?: string): string | number;
 export declare function as_local(value: datetime): datetime;
 export declare function strptime(value: string, format: string, fallback?: datetime | string | undefined | Record<string, datetime | string | boolean>, utc?: boolean): string | datetime | Record<string, string | boolean | datetime>;
+export declare function relative_time(input: datetime): string | datetime;
 export declare function time_since(input: datetime, precision?: number): string | datetime;
 export declare function time_until(input: datetime, precision?: number): string | datetime;
 export declare function as_timedelta(value: string): timedelta | null;

package/dist/utils/time.js

@@ -130,7 +130,7 @@ function timeDiff(input, precision = 1, until = false) {
     if (diff <= 0) {
         return input;
     }
-    if (precision == 0 || precision > 6) {
+    if (precision < 1 || precision > 6) {
         precision = 6;
     }
     const toSeconds = {
@@ -143,23 +143,29 @@ function timeDiff(input, precision = 1, until = false) {
     };
     const units = Object.keys(toSeconds);
     let res = '';
-    let startRes = false;
-    for (let i = 0; i < precision; i++) {
+    let p = 0;
+    for (let i = 0; i < units.length; i++) {
         let value = diff / toSeconds[units[i]];
-        if (i == precision - 1) {
+        if (i == p - 1) {
             value = Math.round(value);
         }
         else {
             value = Math.floor(value);
         }
-        if (startRes || value > 0) {
-            startRes = true;
+        if (value > 0) {
+            p += 1;
             res += ` ${value} ${units[i]}${value != 1 ? 's' : ''}`;
             diff -= value * toSeconds[units[i]];
         }
+        if (res.length && precision == p) {
+            break;
+        }
     }
     return res.trim();
 }
+export function relative_time(input) {
+    return timeDiff(input);
+}
 export function time_since(input, precision = 1) {
     return timeDiff(input, precision);
 }
@@ -174,12 +180,10 @@ export function as_timedelta(value) {
             /^\d*\.?\d*$/.test(value)) {
             let daysStr, timeStr;
             if (value.includes(' ')) {
-                if (value.includes('days')) {
-                    [daysStr, timeStr] = value.split(' days ');
-                }
-                else {
-                    [daysStr, timeStr] = value.split(' ');
-                }
+                [daysStr, timeStr] = value
+                    .replace(/day(s?)/g, '')
+                    .replace(/\s+/g, ' ')
+                    .split(' ');
             }
             else {
                 daysStr = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "ha-nunjucks",
-	"version": "1.4.0",
+	"version": "1.6.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"
@@ -17,7 +17,7 @@
 		"*": "prettier -w"
 	},
 	"author": "Nerwyn",
-	"license": "ISC",
+	"license": "Apache-2.0",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/Nerwyn/ha-nunjucks.git"
@@ -29,6 +29,7 @@
 	"dependencies": {
 		"home-assistant-js-websocket": "latest",
 		"nunjucks": "latest",
+		"slugify": "latest",
 		"ts-py-datetime": "latest"
 	},
 	"devDependencies": {
@@ -39,14 +40,14 @@
 		"eslint": "latest",
 		"eslint-config-prettier": "latest",
 		"eslint-plugin-prettier": "latest",
-		"jsdom-global": "latest",
+		"global-jsdom": "latest",
 		"lint-staged": "latest",
 		"mocha": "latest",
 		"prettier": "latest",
 		"prettier-plugin-organize-imports": "latest",
 		"ts-loader": "latest",
 		"ts-mocha": "latest",
-		"ts-node": "^10.9.2",
+		"ts-node": "latest",
 		"tsx": "latest",
 		"typescript": "latest"
 	}