ha-nunjucks 1.6.1 → 1.6.2

package/README.md

@@ -90,6 +90,10 @@ When the return type is expected to be a number, end users should cast these val
 
 `renderTemplate` will return an empty string for strings that may have been cast from nullish non-numerical values, such as `undefined`, `null`, and `None` (case sensitive).
 
+### Global Environment
+
+ha-nunjucks creates one global object on the browser window, which contains an nunjucks environment used by all custom element instances that use ha-nunjucks. This prevents redundant re-initializing of ha-nunjucks across many custom elements and a significant initial page load speedup. If multiple different custom elements use ha-nunjucks, they will all use the same shared nunjucks environment which is initialized the first time one of them is loaded. ha-nunjucks will also check the version that is loaded, and overwrite it if one custom element has a new version than the currently loaded version.
+
 ## Available Extensions
 
 The vast majority of the [Home Assistant template extensions](https://www.home-assistant.io/docs/configuration/templating/#home-assistant-template-extensions) have been implemented into this package. If there are functions that you use that are not currently supported or don't behave exactly like their jinja2 versions, please make a feature request or try adding it to the project yourself and create a pull request.

package/dist/filters.d.ts

@@ -1,2 +1,2 @@
-import { Environment } from 'nunjucks';
-export declare function addFilters(env: Environment): Environment;
+import { Environment } from 'nunjucks';
+export declare function addFilters(env: Environment): Environment;

package/dist/filters.js

@@ -1,134 +1,134 @@
-import { area_devices, area_entities, area_id, area_name } from './utils/areas';
-import { contains } from './utils/contains';
-import { device_attr, device_entities, device_id, device_name, } from './utils/devices';
-import { closest } from './utils/distance';
-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, 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, date_translated, datetime_translated, number_translated, state_translated, time_translated, } from './utils/state_translated';
-import { has_value, state_attr, states } from './utils/states';
-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) {
-            return FILTERS[func](...args);
-        });
-    }
-    for (const func in HASS_FILTERS) {
-        env.addFilter(func, function (...args) {
-            return HASS_FILTERS[func](window.haNunjucks.hass, ...args);
-        });
-    }
-    return env;
-}
-const HASS_FILTERS = {
-    // States
-    states,
-    state_attr,
-    has_value,
-    // State Translated
-    state_translated,
-    attr_name_translated,
-    attr_value_translated,
-    // Groups
-    expand,
-    // Devices
-    device_entities,
-    device_attr,
-    device_id,
-    device_name,
-    // Floors
-    floor_id,
-    floor_name,
-    floor_areas,
-    floor_entities,
-    // Areas
-    area_id,
-    area_name,
-    area_entities,
-    area_devices,
-    // Labels
-    labels,
-    label_areas,
-    label_devices,
-    label_entities,
-    // IIF
-    iif,
-    // Distance
-    closest,
-};
-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
-    contains,
-    // Numeric
-    // float filter is built into nunjucks
-    is_number,
-    // int filter is built into nunjucks
-    bool,
-    log,
-    sin,
-    cos,
-    tan,
-    asin,
-    acos,
-    atan,
-    atan2,
-    sqrt,
-    max,
-    min,
-    average,
-    median,
-    statistical_mode,
-    bitwise_and,
-    bitwise_or,
-    bitwise_xor,
-    bitwise_not,
-    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,
-};
+import { area_devices, area_entities, area_id, area_name } from './utils/areas';
+import { contains } from './utils/contains';
+import { device_attr, device_entities, device_id, device_name, } from './utils/devices';
+import { closest } from './utils/distance';
+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, 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, date_translated, datetime_translated, number_translated, state_translated, time_translated, } from './utils/state_translated';
+import { has_value, state_attr, states } from './utils/states';
+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) {
+            return FILTERS[func](...args);
+        });
+    }
+    for (const func in HASS_FILTERS) {
+        env.addFilter(func, function (...args) {
+            return HASS_FILTERS[func](window.haNunjucks.hass, ...args);
+        });
+    }
+    return env;
+}
+const HASS_FILTERS = {
+    // States
+    states,
+    state_attr,
+    has_value,
+    // State Translated
+    state_translated,
+    attr_name_translated,
+    attr_value_translated,
+    // Groups
+    expand,
+    // Devices
+    device_entities,
+    device_attr,
+    device_id,
+    device_name,
+    // Floors
+    floor_id,
+    floor_name,
+    floor_areas,
+    floor_entities,
+    // Areas
+    area_id,
+    area_name,
+    area_entities,
+    area_devices,
+    // Labels
+    labels,
+    label_areas,
+    label_devices,
+    label_entities,
+    // IIF
+    iif,
+    // Distance
+    closest,
+};
+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
+    contains,
+    // Numeric
+    // float filter is built into nunjucks
+    is_number,
+    // int filter is built into nunjucks
+    bool,
+    log,
+    sin,
+    cos,
+    tan,
+    asin,
+    acos,
+    atan,
+    atan2,
+    sqrt,
+    max,
+    min,
+    average,
+    median,
+    statistical_mode,
+    bitwise_and,
+    bitwise_or,
+    bitwise_xor,
+    bitwise_not,
+    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,
+};

package/dist/globals.d.ts

@@ -1,2 +1,2 @@
-import { Environment } from 'nunjucks';
-export declare function addGlobals(env: Environment): Environment;
+import { Environment } from 'nunjucks';
+export declare function addGlobals(env: Environment): Environment;

package/dist/globals.js

@@ -1,142 +1,142 @@
-import { area_devices, area_entities, area_id, area_name, areas, } from './utils/areas';
-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_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_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, 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 { 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';
-export function addGlobals(env) {
-    for (const func in GLOBALS) {
-        env.addGlobal(func, function (...args) {
-            return GLOBALS[func](...args);
-        });
-    }
-    for (const func in HASS_GLOBALS) {
-        env.addGlobal(func, function (...args) {
-            return HASS_GLOBALS[func](window.haNunjucks.hass, ...args);
-        });
-    }
-    for (const c in CONST_GLOBALS) {
-        env.addGlobal(c, CONST_GLOBALS[c]);
-    }
-    env.addGlobal('dt', dt);
-    env.addGlobal('date', date);
-    env.addGlobal('time', time);
-    env.addGlobal('datetime', datetime);
-    env.addGlobal('timedelta', timedelta);
-    return env;
-}
-const HASS_GLOBALS = {
-    // States
-    states,
-    is_state,
-    state_attr,
-    is_state_attr,
-    has_value,
-    // State Translated
-    state_translated,
-    attr_name_translated,
-    attr_value_translated,
-    // Groups
-    expand,
-    // Entities
-    is_hidden_entity,
-    // Devices
-    device_entities,
-    device_attr,
-    is_device_attr,
-    device_id,
-    device_name,
-    // Floors
-    floors,
-    floor_id,
-    floor_name,
-    floor_areas,
-    floor_entities,
-    // Areas
-    areas,
-    area_id,
-    area_name,
-    area_entities,
-    area_devices,
-    // Integrations
-    integration_entities,
-    // Labels
-    labels,
-    label_areas,
-    label_devices,
-    label_entities,
-    // Immediate If
-    iif,
-    // Distance
-    distance,
-    closest,
-};
-const GLOBALS = {
-    // Labels
-    label_id,
-    label_name,
-    label_description,
-    // Time
-    now,
-    utcnow,
-    today_at,
-    as_datetime,
-    as_timestamp,
-    as_local,
-    strptime,
-    relative_time,
-    time_since,
-    time_until,
-    as_timedelta,
-    date_translated,
-    time_translated,
-    datetime_translated,
-    // Numeric,
-    float,
-    is_number,
-    int,
-    bool,
-    log,
-    sin,
-    cos,
-    tan,
-    asin,
-    acos,
-    atan,
-    atan2,
-    sqrt,
-    max,
-    min,
-    average,
-    median,
-    statistical_mode,
-    number_translated,
-    // Type Conversions
-    set,
-    list,
-    str,
-    // Iterating Multiple Objects
-    zip,
-    // String fitlers
-    slugify,
-    // Miscellaneous
-    match_media,
-};
-const CONST_GLOBALS = {
-    e,
-    pi,
-    tau,
-    inf,
-};
+import { area_devices, area_entities, area_id, area_name, areas, } from './utils/areas';
+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_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_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, 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 { 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';
+export function addGlobals(env) {
+    for (const func in GLOBALS) {
+        env.addGlobal(func, function (...args) {
+            return GLOBALS[func](...args);
+        });
+    }
+    for (const func in HASS_GLOBALS) {
+        env.addGlobal(func, function (...args) {
+            return HASS_GLOBALS[func](window.haNunjucks.hass, ...args);
+        });
+    }
+    for (const c in CONST_GLOBALS) {
+        env.addGlobal(c, CONST_GLOBALS[c]);
+    }
+    env.addGlobal('dt', dt);
+    env.addGlobal('date', date);
+    env.addGlobal('time', time);
+    env.addGlobal('datetime', datetime);
+    env.addGlobal('timedelta', timedelta);
+    return env;
+}
+const HASS_GLOBALS = {
+    // States
+    states,
+    is_state,
+    state_attr,
+    is_state_attr,
+    has_value,
+    // State Translated
+    state_translated,
+    attr_name_translated,
+    attr_value_translated,
+    // Groups
+    expand,
+    // Entities
+    is_hidden_entity,
+    // Devices
+    device_entities,
+    device_attr,
+    is_device_attr,
+    device_id,
+    device_name,
+    // Floors
+    floors,
+    floor_id,
+    floor_name,
+    floor_areas,
+    floor_entities,
+    // Areas
+    areas,
+    area_id,
+    area_name,
+    area_entities,
+    area_devices,
+    // Integrations
+    integration_entities,
+    // Labels
+    labels,
+    label_areas,
+    label_devices,
+    label_entities,
+    // Immediate If
+    iif,
+    // Distance
+    distance,
+    closest,
+};
+const GLOBALS = {
+    // Labels
+    label_id,
+    label_name,
+    label_description,
+    // Time
+    now,
+    utcnow,
+    today_at,
+    as_datetime,
+    as_timestamp,
+    as_local,
+    strptime,
+    relative_time,
+    time_since,
+    time_until,
+    as_timedelta,
+    date_translated,
+    time_translated,
+    datetime_translated,
+    // Numeric,
+    float,
+    is_number,
+    int,
+    bool,
+    log,
+    sin,
+    cos,
+    tan,
+    asin,
+    acos,
+    atan,
+    atan2,
+    sqrt,
+    max,
+    min,
+    average,
+    median,
+    statistical_mode,
+    number_translated,
+    // Type Conversions
+    set,
+    list,
+    str,
+    // Iterating Multiple Objects
+    zip,
+    // String fitlers
+    slugify,
+    // Miscellaneous
+    match_media,
+};
+const CONST_GLOBALS = {
+    e,
+    pi,
+    tau,
+    inf,
+};

package/dist/helpers.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Call a handler function when a ready function returns true.
+ * If the ready function returns false, this method recursively recalls itself on a timeout.
+ * The function continues to recall itself with an exponentially increasing timeout until
+ * the ready function returns true or the timeout is exceeded.
+ * @param {() => void | Promise<void>} handler The function to call when ready
+ * @param {() => boolean | Promise<boolean>} handleReady The function to check and return true when ready
+ * @param {number} timeout The max time to wait in milliseconds, defaults to 20000
+ * @param {number} delay The initial delay in milliseconds, defaults to 10
+ */
+export declare function handleWhenReady(handler: () => void | Promise<void>, handleReady: () => boolean | Promise<boolean>, timeout?: number, delay?: number, errorMessage?: string): Promise<void>;
+/**
+ * Compare two semantic versions
+ * @param {string} v1
+ * @param {string} v2
+ * @returns {1 | 0 | -1}
+ */
+export declare function compareVersions(v1: string, v2: string): 1 | 0 | -1;

package/dist/helpers.js

@@ -0,0 +1,71 @@
+/**
+ * Call a handler function when a ready function returns true.
+ * If the ready function returns false, this method recursively recalls itself on a timeout.
+ * The function continues to recall itself with an exponentially increasing timeout until
+ * the ready function returns true or the timeout is exceeded.
+ * @param {() => void | Promise<void>} handler The function to call when ready
+ * @param {() => boolean | Promise<boolean>} handleReady The function to check and return true when ready
+ * @param {number} timeout The max time to wait in milliseconds, defaults to 20000
+ * @param {number} delay The initial delay in milliseconds, defaults to 10
+ */
+export async function handleWhenReady(handler, handleReady, timeout = 20000, delay = 10, errorMessage = `handleWhenReady ${timeout}ms timeout exceeded`) {
+    if (delay > timeout) {
+        console.error(errorMessage);
+        return;
+    }
+    if (!(await handleReady())) {
+        setTimeout(async () => await handleWhenReady(handler, handleReady, timeout, delay * 2), delay);
+        return;
+    }
+    await handler();
+}
+const prereleaseOrder = {
+    dev: 0,
+    alpha: 1,
+    beta: 2,
+    rc: 3,
+    release: 4,
+};
+/**
+ * Get Semantic Version object from version string
+ * @param {string} version
+ * @returns {SemanticVersion}
+ */
+function getSemanticVersion(version) {
+    const [mmp, prerelease] = version.split('-');
+    const [major, minor, patch] = mmp.split('.').map(Number);
+    const [pOrder, pVersion] = prerelease?.split('.') || ['release', '0'];
+    return {
+        major: major || 0,
+        minor: minor || 0,
+        patch: patch || 0,
+        prerelease: prereleaseOrder[pOrder] ?? 4,
+        prereleaseVersion: isNaN(Number(pVersion)) ? 0 : Number(pVersion),
+    };
+}
+/**
+ * Compare two semantic versions
+ * @param {string} v1
+ * @param {string} v2
+ * @returns {1 | 0 | -1}
+ */
+export function compareVersions(v1, v2) {
+    if (v1 == v2) {
+        return 0;
+    }
+    const sv1 = getSemanticVersion(v1);
+    const sv2 = getSemanticVersion(v2);
+    const fields = [
+        'major',
+        'minor',
+        'patch',
+        'prerelease',
+        'prereleaseVersion',
+    ];
+    for (const field of fields) {
+        if (sv1[field] != sv2[field]) {
+            return sv1[field] > sv2[field] ? 1 : -1;
+        }
+    }
+    return 0;
+}