perf(bundle): lazy-load the nunjucks template engine (#2535)
Closes #2531. ## Summary The full `nunjucks` templating engine (~226KB) plus `ha-nunjucks` (~46KB) — roughly **272KB, ~13% of the eager entry chunk** — was statically imported and downloaded by every card on initial load, even though templates only apply when a config value contains a `{{ … }}` / `{% … %}` delimiter. Most cards use no templates and never need the engine. This defers the engine behind a dynamic `import('ha-nunjucks/dist')` so it ships in a separate, on-demand chunk instead of the eager `card-*.js`. ## Approach The render path (`TemplateRenderer.renderRecursively`) is **kept synchronous** — it is called from many synchronous hot paths (condition/trigger evaluators, picture-elements rendering, actions, folder matchers), and making it async would be a large, high-risk refactor of the evaluation core. Instead: - **New `src/card-controller/templates/engine.ts`** — a module-level singleton lazy loader (`loadTemplateEngine()` / `getTemplateEngine()`) shared across all `TemplateRenderer` instances, plus a `containsTemplate()` delimiter helper. - **Delimiter gating** — strings without a delimiter never touch the engine (the overwhelming majority of renders). - **Pre-warm at config time** — because every template string originates in the config, a new mandatory `TEMPLATE_ENGINE` initialization aspect loads the engine before first render whenever the config contains a delimiter. This **guarantees no raw `{{ … }}` flash**: content/condition rendering is blocked until the engine is present for template-using cards. Cards without templates never load it. ## Result - nunjucks + ha-nunjucks move out of the eager chunk into a separate chunk fetched only when a card actually uses templates. - No change to the synchronous public render API; condition/trigger evaluation core untouched. ## Tests - New `engine.ts` loader coverage (concurrent load, cached reuse, not-loaded fallback). - The 11 existing test files that render real (delimiter-bearing) templates declare their dependency explicitly via `beforeAll(loadTemplateEngine)` — no global/implicit setup hook. - Full suite green (4764 tests), lint and ts-prune clean, per-file 100% coverage maintained for the affected directories. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_016ykWemdkZrgywvC71pHc6c --- _Generated by [Claude Code](https://claude.ai/code/session_016ykWemdkZrgywvC71pHc6c)_
This commit is contained in:
Dermot Duffy
committed by
dermotduffy
dermotduffy
parent
b33c034810
commit
ea251ca988
@@ -1,12 +1,16 @@
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import { beforeAll, describe, expect, it } from 'vitest';
|
||||
|
||||
import { TemplateRenderer } from '../../../src/card-controller/templates';
|
||||
import { TemplateManager } from '../../../src/card-controller/templates';
|
||||
import { renderTimePeriodToSeconds } from '../../../src/condition-trigger/common/time-period';
|
||||
import { createHASS, createStateEntity } from '../../test-utils';
|
||||
import {
|
||||
createHASS,
|
||||
createMockTemplateRenderer,
|
||||
createStateEntity,
|
||||
} from '../../test-utils';
|
||||
|
||||
// @vitest-environment jsdom
|
||||
describe('renderTimePeriodToSeconds', () => {
|
||||
const createRenderer = (): TemplateRenderer => new TemplateRenderer();
|
||||
const templateManager = createMockTemplateRenderer();
|
||||
|
||||
const createStateWithDelay = (delay: string) => ({
|
||||
hass: createHASS({ 'input_number.delay': createStateEntity({ state: delay }) }),
|
||||
@@ -14,86 +18,94 @@ describe('renderTimePeriodToSeconds', () => {
|
||||
|
||||
// Without `hass` the value is parsed as-is, matching HA's `cv.time_period`.
|
||||
it('should accept a number of seconds', () => {
|
||||
expect(renderTimePeriodToSeconds(createRenderer(), 5)).toBe(5);
|
||||
expect(renderTimePeriodToSeconds(createRenderer(), 0)).toBe(0);
|
||||
expect(renderTimePeriodToSeconds(templateManager, 5)).toBe(5);
|
||||
expect(renderTimePeriodToSeconds(templateManager, 0)).toBe(0);
|
||||
});
|
||||
|
||||
it('should reject a negative period', () => {
|
||||
expect(renderTimePeriodToSeconds(createRenderer(), -1)).toBeNull();
|
||||
expect(renderTimePeriodToSeconds(createRenderer(), { seconds: -5 })).toBeNull();
|
||||
expect(renderTimePeriodToSeconds(templateManager, -1)).toBeNull();
|
||||
expect(renderTimePeriodToSeconds(templateManager, { seconds: -5 })).toBeNull();
|
||||
});
|
||||
|
||||
it('should parse a bare numeric string as seconds', () => {
|
||||
expect(renderTimePeriodToSeconds(createRenderer(), '5')).toBe(5);
|
||||
expect(renderTimePeriodToSeconds(templateManager, '5')).toBe(5);
|
||||
});
|
||||
|
||||
it('should read HH:MM and HH:MM:SS (two parts are hours:minutes, as in HA)', () => {
|
||||
expect(renderTimePeriodToSeconds(createRenderer(), '01:30')).toBe(5400);
|
||||
expect(renderTimePeriodToSeconds(createRenderer(), '00:05')).toBe(300);
|
||||
expect(renderTimePeriodToSeconds(createRenderer(), '00:00:05')).toBe(5);
|
||||
expect(renderTimePeriodToSeconds(createRenderer(), '1:00:00')).toBe(3600);
|
||||
expect(renderTimePeriodToSeconds(templateManager, '01:30')).toBe(5400);
|
||||
expect(renderTimePeriodToSeconds(templateManager, '00:05')).toBe(300);
|
||||
expect(renderTimePeriodToSeconds(templateManager, '00:00:05')).toBe(5);
|
||||
expect(renderTimePeriodToSeconds(templateManager, '1:00:00')).toBe(3600);
|
||||
});
|
||||
|
||||
it('should reject unparseable, empty-part, or over-long strings', () => {
|
||||
expect(renderTimePeriodToSeconds(createRenderer(), 'not-a-duration')).toBeNull();
|
||||
expect(renderTimePeriodToSeconds(createRenderer(), '1:ab')).toBeNull();
|
||||
expect(renderTimePeriodToSeconds(createRenderer(), '1:2:3:4')).toBeNull();
|
||||
expect(renderTimePeriodToSeconds(createRenderer(), '5:')).toBeNull();
|
||||
expect(renderTimePeriodToSeconds(createRenderer(), '')).toBeNull();
|
||||
expect(renderTimePeriodToSeconds(templateManager, 'not-a-duration')).toBeNull();
|
||||
expect(renderTimePeriodToSeconds(templateManager, '1:ab')).toBeNull();
|
||||
expect(renderTimePeriodToSeconds(templateManager, '1:2:3:4')).toBeNull();
|
||||
expect(renderTimePeriodToSeconds(templateManager, '5:')).toBeNull();
|
||||
expect(renderTimePeriodToSeconds(templateManager, '')).toBeNull();
|
||||
});
|
||||
|
||||
it('should accept a {days, hours, minutes, seconds, milliseconds} dict', () => {
|
||||
expect(renderTimePeriodToSeconds(createRenderer(), { seconds: 5 })).toBe(5);
|
||||
expect(renderTimePeriodToSeconds(createRenderer(), { hours: 1, minutes: 30 })).toBe(
|
||||
expect(renderTimePeriodToSeconds(templateManager, { seconds: 5 })).toBe(5);
|
||||
expect(renderTimePeriodToSeconds(templateManager, { hours: 1, minutes: 30 })).toBe(
|
||||
5400,
|
||||
);
|
||||
expect(renderTimePeriodToSeconds(createRenderer(), { days: 1 })).toBe(86400);
|
||||
expect(renderTimePeriodToSeconds(createRenderer(), { milliseconds: 500 })).toBe(0.5);
|
||||
expect(renderTimePeriodToSeconds(createRenderer(), {})).toBe(0);
|
||||
expect(renderTimePeriodToSeconds(templateManager, { days: 1 })).toBe(86400);
|
||||
expect(renderTimePeriodToSeconds(templateManager, { milliseconds: 500 })).toBe(0.5);
|
||||
expect(renderTimePeriodToSeconds(templateManager, {})).toBe(0);
|
||||
});
|
||||
|
||||
it('should coerce a numeric-string dict field', () => {
|
||||
expect(renderTimePeriodToSeconds(createRenderer(), { minutes: '2' })).toBe(120);
|
||||
expect(renderTimePeriodToSeconds(createRenderer(), { minutes: 'nope' })).toBeNull();
|
||||
expect(renderTimePeriodToSeconds(templateManager, { minutes: '2' })).toBe(120);
|
||||
expect(renderTimePeriodToSeconds(templateManager, { minutes: 'nope' })).toBeNull();
|
||||
});
|
||||
|
||||
// With `hass`, templates are rendered against the current state before parsing.
|
||||
it('should render and parse a template string', () => {
|
||||
expect(
|
||||
renderTimePeriodToSeconds(
|
||||
createRenderer(),
|
||||
"{{ states('input_number.delay') }}",
|
||||
createStateWithDelay('5'),
|
||||
),
|
||||
).toBe(5);
|
||||
});
|
||||
describe('with templates', () => {
|
||||
const templateManager = new TemplateManager();
|
||||
|
||||
it('should render and parse template fields in a dict', () => {
|
||||
expect(
|
||||
renderTimePeriodToSeconds(
|
||||
createRenderer(),
|
||||
{ minutes: "{{ states('input_number.delay') }}" },
|
||||
createStateWithDelay('2'),
|
||||
),
|
||||
).toBe(120);
|
||||
});
|
||||
beforeAll(async () => {
|
||||
await templateManager.loadRenderer();
|
||||
});
|
||||
|
||||
it('should return null when a template renders to a non-duration value', () => {
|
||||
// A string that is not a number.
|
||||
expect(
|
||||
renderTimePeriodToSeconds(
|
||||
createRenderer(),
|
||||
"{{ states('input_number.delay') }}",
|
||||
createStateWithDelay('nope'),
|
||||
),
|
||||
).toBeNull();
|
||||
// A value that is neither a number, string nor dict (here, a boolean).
|
||||
expect(
|
||||
renderTimePeriodToSeconds(
|
||||
createRenderer(),
|
||||
"{{ is_state('input_number.delay', 'x') }}",
|
||||
createStateWithDelay('5'),
|
||||
),
|
||||
).toBeNull();
|
||||
it('should render and parse a template string', () => {
|
||||
expect(
|
||||
renderTimePeriodToSeconds(
|
||||
templateManager,
|
||||
"{{ states('input_number.delay') }}",
|
||||
createStateWithDelay('5'),
|
||||
),
|
||||
).toBe(5);
|
||||
});
|
||||
|
||||
it('should render and parse template fields in a dict', () => {
|
||||
expect(
|
||||
renderTimePeriodToSeconds(
|
||||
templateManager,
|
||||
{ minutes: "{{ states('input_number.delay') }}" },
|
||||
createStateWithDelay('2'),
|
||||
),
|
||||
).toBe(120);
|
||||
});
|
||||
|
||||
it('should return null when a template renders to a non-duration value', () => {
|
||||
// A string that is not a number.
|
||||
expect(
|
||||
renderTimePeriodToSeconds(
|
||||
templateManager,
|
||||
"{{ states('input_number.delay') }}",
|
||||
createStateWithDelay('nope'),
|
||||
),
|
||||
).toBeNull();
|
||||
// A value that is neither a number, string nor dict (here, a boolean).
|
||||
expect(
|
||||
renderTimePeriodToSeconds(
|
||||
templateManager,
|
||||
"{{ is_state('input_number.delay', 'x') }}",
|
||||
createStateWithDelay('5'),
|
||||
),
|
||||
).toBeNull();
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user