feat: Add folder title matching and parsing (#2067)

This is a breaking change for users of the [experimental 'folder'
functionality](https://card.camera/#/configuration/folders).

Related: #1748
This commit is contained in:
Dermot Duffy
2025-05-27 07:50:51 -07:00
committed by GitHub
parent c4400194f5
commit c077f8bf70
35 changed files with 1038 additions and 378 deletions
+97 -155
View File
@@ -3,6 +3,8 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
import { HAFoldersEngine } from '../../../../src/card-controller/folders/ha/engine';
import { FolderQuery } from '../../../../src/card-controller/folders/types';
import { FolderConfig } from '../../../../src/config/schema/folders';
import { BrowseMediaViewFolder } from '../../../../src/ha/browse-media/item';
import { browseMediaSchema } from '../../../../src/ha/browse-media/types';
import { getMediaDownloadPath } from '../../../../src/ha/download';
import { homeAssistantWSRequest } from '../../../../src/ha/ws-request';
import { Endpoint } from '../../../../src/types';
@@ -73,17 +75,6 @@ describe('HAFoldersEngine', () => {
});
});
describe('expandFolder', () => {
it('should reject folders of the wrong type', async () => {
const query = {
folder: { type: 'UNKNOWN' },
} as unknown as FolderQuery;
const engine = new HAFoldersEngine();
expect(await engine.expandFolder(createHASS(), query)).toBeNull();
});
});
describe('should generate default folder query', () => {
it('should generate default folder query', () => {
const folder: FolderConfig = { type: 'ha' };
@@ -92,7 +83,7 @@ describe('HAFoldersEngine', () => {
const query = engine.generateDefaultFolderQuery(folder);
expect(query).toEqual({
folder,
path: [{ id: 'media-source://', ha: { id: 'media-source://' } }],
path: [{ ha: { id: 'media-source://' } }],
});
});
@@ -113,10 +104,7 @@ describe('HAFoldersEngine', () => {
const engine = new HAFoldersEngine();
expect(engine.generateDefaultFolderQuery(folder)).toEqual({
folder,
path: [
{ id: 'media-source://1', ha: { id: 'media-source://1' } },
{ id: 'media-source://2', ha: { id: 'media-source://2' } },
],
path: [{ ha: { id: 'media-source://1' } }, { ha: { id: 'media-source://2' } }],
});
});
@@ -125,28 +113,39 @@ describe('HAFoldersEngine', () => {
const engine = new HAFoldersEngine();
expect(engine.generateDefaultFolderQuery(folder)).toEqual({
folder,
path: [{ id: 'media-source://', ha: { id: 'media-source://' } }],
path: [{ ha: { id: 'media-source://' } }],
});
});
it('should add default media root as necessary', async () => {
const folder = createFolder({ ha: { path: [{ title: 'Frigate' }] } });
const folder = createFolder({
ha: { path: [{ matchers: [{ type: 'title', title: 'Frigate' }] }] },
});
const engine = new HAFoldersEngine();
expect(engine.generateDefaultFolderQuery(folder)).toEqual({
folder,
path: [
{ id: 'media-source://', ha: { id: 'media-source://' } },
{ id: undefined, ha: { title: 'Frigate' } },
{ ha: { id: 'media-source://' } },
{ ha: { matchers: [{ type: 'title', title: 'Frigate' }] } },
],
});
});
});
describe('should expand folder', () => {
it('should reject folders of the wrong type', async () => {
const query = {
folder: { type: 'UNKNOWN' },
} as unknown as FolderQuery;
const engine = new HAFoldersEngine();
expect(await engine.expandFolder(createHASS(), query)).toBeNull();
});
it('should expand folder with cache by default', async () => {
const query: FolderQuery = {
folder: { type: 'ha' },
path: [{ id: 'media-source://id' }],
path: [{ ha: { id: 'media-source://id' } }],
};
vi.mocked(homeAssistantWSRequest).mockResolvedValueOnce(
@@ -183,7 +182,7 @@ describe('HAFoldersEngine', () => {
it('should expand folder without cache when requested', async () => {
const query: FolderQuery = {
folder: { type: 'ha' },
path: [{ id: 'media-source://id' }],
path: [{ ha: { id: 'media-source://id' } }],
};
vi.mocked(homeAssistantWSRequest)
@@ -221,150 +220,93 @@ describe('HAFoldersEngine', () => {
expect(homeAssistantWSRequest).toBeCalledTimes(2);
});
it('should use id from browsemedia in folder in query', async () => {
const browseMedia = createBrowseMedia({
media_content_id: 'media-source://id',
can_expand: true,
});
const query: FolderQuery = {
folder: { type: 'ha' },
path: [
{
folder: new BrowseMediaViewFolder(createFolder(), browseMedia),
},
],
};
vi.mocked(homeAssistantWSRequest).mockResolvedValueOnce(
createBrowseMedia({
media_content_id: 'media-source://id',
can_expand: true,
children: [],
}),
);
const hass = createHASS();
const engine = new HAFoldersEngine();
await engine.expandFolder(hass, query);
expect(homeAssistantWSRequest).toBeCalledWith(hass, browseMediaSchema, {
type: 'media_source/browse_media',
media_content_id: 'media-source://id',
});
});
it('should not expand without a folder with an id', async () => {
const query: FolderQuery = {
folder: { type: 'ha' },
// There's no component in the query with an id to start from.
path: [{ ha: { title: 'Frigate' } }],
path: [{ ha: {} }],
};
const engine = new HAFoldersEngine();
expect(await engine.expandFolder(createHASS(), query)).toBeNull();
});
it('should expand folder with title based query', async () => {
const query: FolderQuery = {
folder: { type: 'ha' },
path: [{ id: 'media-source://' }, { ha: { title: 'Frigate' } }],
};
describe('should apply matchers', async () => {
it('should expand folder with title based query', async () => {
const query: FolderQuery = {
folder: { type: 'ha' },
path: [
{ ha: { id: 'media-source://' } },
{ ha: { matchers: [{ type: 'title', title: 'Frigate' }] } },
{},
],
};
vi.mocked(homeAssistantWSRequest)
.mockResolvedValueOnce(
createBrowseMedia({
media_content_id: 'media-source://',
can_expand: true,
children: [
createBrowseMedia({
media_content_id: 'media-source://frigate',
title: 'Frigate',
can_expand: true,
}),
],
}),
)
.mockResolvedValueOnce(
createBrowseMedia({
media_content_id: 'media-source://frigate',
can_expand: true,
children: [
createBrowseMedia({
media_content_id: 'media-source://frigate/result',
title: 'Result',
}),
],
}),
);
vi.mocked(homeAssistantWSRequest)
.mockResolvedValueOnce(
createBrowseMedia({
media_content_id: 'media-source://',
can_expand: true,
children: [
createBrowseMedia({
media_content_id: 'media-source://frigate',
title: 'Frigate',
can_expand: true,
}),
],
}),
)
.mockResolvedValueOnce(
createBrowseMedia({
media_content_id: 'media-source://frigate',
can_expand: true,
children: [
createBrowseMedia({
media_content_id: 'media-source://frigate/result',
title: 'Result',
}),
],
}),
);
const engine = new HAFoldersEngine();
const results = await engine.expandFolder(createHASS(), query);
expect(results?.length).toBe(1);
expect(results?.[0]).toBeInstanceOf(ViewMedia);
expect(results?.[0].getID()).toBe('media-source://frigate/result');
});
it('should expand folder with title_re based query', async () => {
const query: FolderQuery = {
folder: { type: 'ha' },
path: [{ id: 'media-source://' }, { ha: { title_re: 'Fri.*' } }],
};
vi.mocked(homeAssistantWSRequest)
.mockResolvedValueOnce(
createBrowseMedia({
media_content_id: 'media-source://',
can_expand: true,
children: [
createBrowseMedia({
media_content_id: 'media-source://frigate',
title: 'Frigate',
can_expand: true,
}),
],
}),
)
.mockResolvedValueOnce(
createBrowseMedia({
media_content_id: 'media-source://frigate',
can_expand: true,
children: [
createBrowseMedia({
media_content_id: 'media-source://frigate/result',
title: 'Result',
}),
],
}),
);
const engine = new HAFoldersEngine();
const results = await engine.expandFolder(createHASS(), query);
expect(results?.length).toBe(1);
expect(results?.[0]).toBeInstanceOf(ViewMedia);
expect(results?.[0].getID()).toBe('media-source://frigate/result');
});
it('should expand folder with ha id based query', async () => {
const query: FolderQuery = {
folder: { type: 'ha' },
path: [
{ id: 'media-source://' },
{ ha: { title: 'Frigate' } },
{ id: 'media-source://frigate/subdir' },
],
};
vi.mocked(homeAssistantWSRequest)
.mockResolvedValueOnce(
createBrowseMedia({
media_content_id: 'media-source://',
can_expand: true,
children: [
createBrowseMedia({
media_content_id: 'media-source://frigate',
title: 'Frigate',
can_expand: true,
}),
],
}),
)
.mockResolvedValueOnce(
createBrowseMedia({
media_content_id: 'media-source://frigate',
can_expand: true,
children: [
createBrowseMedia({
media_content_id: 'media-source://frigate/subdir',
can_expand: true,
}),
],
}),
)
.mockResolvedValueOnce(
createBrowseMedia({
media_content_id: 'media-source://frigate/subdir',
can_expand: true,
children: [
createBrowseMedia({
media_content_id: 'media-source://frigate/subdir/result',
title: 'Result',
}),
],
}),
);
const engine = new HAFoldersEngine();
const results = await engine.expandFolder(createHASS(), query);
expect(results?.length).toBe(1);
expect(results?.[0]).toBeInstanceOf(ViewMedia);
expect(results?.[0].getID()).toBe('media-source://frigate/subdir/result');
const engine = new HAFoldersEngine();
const results = await engine.expandFolder(createHASS(), query);
expect(results?.length).toBe(1);
expect(results?.[0]).toBeInstanceOf(ViewMedia);
expect(results?.[0].getID()).toBe('media-source://frigate/result');
});
});
});
});
@@ -0,0 +1,166 @@
import { describe, expect, it } from 'vitest';
import { MediaMatcher } from '../../../../src/card-controller/folders/ha/media-matcher';
import { Matcher } from '../../../../src/config/schema/folders';
import { BrowseMedia } from '../../../../src/ha/browse-media/types';
describe('MediaMatcher', () => {
describe('match', () => {
const createMediaItem = (
title: string,
can_expand: boolean,
media_class = 'image',
): BrowseMedia => ({
title,
media_class,
media_content_type: media_class === 'directory' ? 'directory' : 'image/jpeg',
media_content_id: `${media_class}_${title.replace(/\s+/g, '_')}`,
can_play: media_class !== 'directory',
can_expand,
thumbnail: null,
});
it('should return false if foldersOnly is true and media.can_expand is false', () => {
const mediaMatcher = new MediaMatcher();
const media = createMediaItem('Test File', false);
expect(mediaMatcher.match(media, [], true)).toBe(false);
});
it('should return true if foldersOnly is true and media.can_expand is true', () => {
const mediaMatcher = new MediaMatcher();
const media = createMediaItem('Test Folder', true, 'directory');
expect(mediaMatcher.match(media, [], true)).toBe(true);
});
it('should return true if matchers array is empty', () => {
const mediaMatcher = new MediaMatcher();
const media = createMediaItem('Test Media', false);
expect(mediaMatcher.match(media, [])).toBe(true);
});
it('should return true if matchers array is undefined', () => {
const mediaMatcher = new MediaMatcher();
const media = createMediaItem('Test Media', false);
expect(mediaMatcher.match(media, undefined)).toBe(true);
});
describe('with title matcher', () => {
it('should return true when title matches exactly', () => {
const mediaMatcher = new MediaMatcher();
const media = createMediaItem('Exact Title', false);
const matchers: Matcher[] = [{ type: 'title', title: 'Exact Title' }];
expect(mediaMatcher.match(media, matchers)).toBe(true);
});
it('should return false when title does not match exactly', () => {
const mediaMatcher = new MediaMatcher();
const media = createMediaItem('DOES NOT MATCH', false);
const matchers: Matcher[] = [{ type: 'title', title: 'Exact Title' }];
expect(mediaMatcher.match(media, matchers)).toBe(false);
});
it('should return true when title matches regexp and extracted value matches matcher.title', () => {
const mediaMatcher = new MediaMatcher();
const media = createMediaItem('Prefix-ImportantPart-Suffix', false);
const matchers: Matcher[] = [
{
type: 'title',
regexp: '^Prefix-(?<value>ImportantPart)-Suffix$',
title: 'ImportantPart',
},
];
expect(mediaMatcher.match(media, matchers)).toBe(true);
});
it('should return false when title matches regexp but extracted value does not match matcher.title', () => {
const mediaMatcher = new MediaMatcher();
const media = createMediaItem('Prefix-ImportantPart-Suffix', false);
const matchers: Matcher[] = [
{
type: 'title',
regexp: '^Prefix-(?<value>ImportantPart)-Suffix$',
title: 'WrongPart',
},
];
expect(mediaMatcher.match(media, matchers)).toBe(false);
});
it('should return true when title matches regexp with an explicit title value', () => {
const mediaMatcher = new MediaMatcher();
const media = createMediaItem('Prefix-ImportantPart-Suffix', false);
const matchers: Matcher[] = [
{
type: 'title',
regexp: '^Prefix-(?<value>ImportantPart)-Suffix$',
// title is undefined.
},
];
expect(mediaMatcher.match(media, matchers)).toBe(true);
});
it('should return false when title does not match regexp', () => {
const mediaMatcher = new MediaMatcher();
const media = createMediaItem('Unrelated Title', false);
const matchers: Matcher[] = [
{
type: 'title',
regexp: '^Prefix-(?<value>ImportantPart)-Suffix$',
title: 'ImportantPart',
},
];
expect(mediaMatcher.match(media, matchers)).toBe(false);
});
it('should return false when regexp is provided but does not extract the required group', () => {
const mediaMatcher = new MediaMatcher();
const media = createMediaItem('Prefix-ImportantPart-Suffix', false);
const matchers: Matcher[] = [
{
type: 'title',
regexp: `^Prefix-ImportantPart-Suffix$`, // No named group
title: 'ImportantPart',
},
];
expect(mediaMatcher.match(media, matchers)).toBe(false);
});
it('should return true when no regexp and no matcher.title (matches any title)', () => {
const mediaMatcher = new MediaMatcher();
const media = createMediaItem('Any Title Will Do', false);
const matchers: Matcher[] = [{ type: 'title' }];
expect(mediaMatcher.match(media, matchers)).toBe(true);
});
});
it('should return false if one of multiple matchers fails', () => {
const mediaMatcher = new MediaMatcher();
const media = createMediaItem('Test Media One', false);
const matchers: Matcher[] = [
{ type: 'title', title: 'Test Media One' }, // Pass
{ type: 'title', title: 'Test Media Two' }, // Fail
];
expect(mediaMatcher.match(media, matchers)).toBe(false);
});
it('should return true if all multiple matchers pass', () => {
const mediaMatcher = new MediaMatcher();
const media = createMediaItem('Test Media One', false);
const matchers: Matcher[] = [
{ type: 'title', title: 'Test Media One' },
{
type: 'title',
regexp: `^(?<value>Test Media One)$`,
title: 'Test Media One',
},
];
expect(mediaMatcher.match(media, matchers)).toBe(true);
});
it('should ignore matchers of unknown types', () => {
const mediaMatcher = new MediaMatcher();
const media = createMediaItem('Test Media', false);
const matchers: Matcher[] = [{ type: 'unknownMatcherType' as 'title' }];
expect(mediaMatcher.match(media, matchers)).toBe(true);
});
});
});
@@ -0,0 +1,191 @@
import { describe, expect, it } from 'vitest';
import { MetadataGenerator } from '../../../../src/card-controller/folders/ha/metadata-generator';
import { Parser } from '../../../../src/config/schema/folders';
import { createBrowseMedia, createRichBrowseMedia } from '../../../test-utils';
describe('MetadataGenerator', () => {
const browseMedia = createBrowseMedia({
title: 'Test Media 2025-05-26 18:18',
});
const expectedDate = new Date('2025-05-26T18:18:00.000Z');
const formatlessDateParser: Parser = {
type: 'startdate',
};
describe('should dynamically import any-date-parser when needed', () => {
it('should not import any-date-parser if no parsers require it', async () => {
const generator = new MetadataGenerator();
await generator.prepare([
// Pretend no parsers require unknown date formats.
]);
expect(
generator.generate(browseMedia, undefined, [formatlessDateParser])?.startDate,
).toBeUndefined();
});
it('should import any-date-parser if a parser requires it', async () => {
const generator = new MetadataGenerator();
await generator.prepare([formatlessDateParser]);
expect(
generator.generate(browseMedia, undefined, [formatlessDateParser])?.startDate,
).toEqual(expectedDate);
// Re-preparing should nothing.
await generator.prepare([formatlessDateParser]);
expect(
generator.generate(browseMedia, undefined, [formatlessDateParser])?.startDate,
).toEqual(expectedDate);
});
});
describe('should generate metadata', () => {
it('should not generate metadata without an parsers', async () => {
const generator = new MetadataGenerator();
await generator.prepare([]);
expect(generator.generate(browseMedia)).toBeNull();
});
it('should ignore unknown parsers', async () => {
const goodParser: Parser = {
type: 'date',
};
const badParser: Parser = {
type: 'UNKNOWN' as 'date',
};
const generator = new MetadataGenerator();
await generator.prepare([goodParser, badParser]);
expect(
generator.generate(browseMedia, undefined, [goodParser, badParser]),
).toEqual({
startDate: expectedDate,
});
});
describe('should generate date metadata', () => {
describe('should generate date metadata without a date format', () => {
it('should generate start date without a date format', async () => {
const generator = new MetadataGenerator();
await generator.prepare([formatlessDateParser]);
expect(
generator.generate(browseMedia, undefined, [formatlessDateParser])
?.startDate,
).toEqual(expectedDate);
});
it('should treat date as an alias for the startdate parser', async () => {
const parser: Parser = {
type: 'date',
};
const generator = new MetadataGenerator();
await generator.prepare([parser]);
expect(
generator.generate(browseMedia, undefined, [parser])?.startDate,
).toEqual(expectedDate);
});
it('should not parse when regexp fails to match', async () => {
const parser: Parser = {
type: 'date',
regexp: 'WILL_NOT_MATCH',
};
const generator = new MetadataGenerator();
await generator.prepare([parser]);
expect(
generator.generate(browseMedia, undefined, [parser])?.startDate,
).toBeUndefined();
});
it('should fail to generate start date without a date format', async () => {
const badBrowseMedia = createBrowseMedia({
title: 'Test Media NO DATE',
});
const generator = new MetadataGenerator();
await generator.prepare([formatlessDateParser]);
expect(
generator.generate(badBrowseMedia, undefined, [formatlessDateParser])
?.startDate,
).toBeUndefined();
});
it('should incorporate parent metadata without a date format', async () => {
const parentBrowseMedia = createRichBrowseMedia({
title: '2025-05-26',
_metadata: {
startDate: new Date('2025-05-26T00:00:00.000Z'),
},
});
const childBrowseMedia = createBrowseMedia({
title: '22:42',
});
const generator = new MetadataGenerator();
await generator.prepare([formatlessDateParser]);
expect(
generator.generate(childBrowseMedia, parentBrowseMedia, [
formatlessDateParser,
])?.startDate,
).toEqual(new Date('2025-05-26T22:42:00.000Z'));
});
});
describe('should generate date metadata with a date format', () => {
it('should generate start date with a date formater and a regexp', async () => {
const dateParser: Parser = {
type: 'startdate',
format: 'yyyy-MM-dd HH:mm',
regexp: 'Test Media (?<value>.*)',
};
const generator = new MetadataGenerator();
await generator.prepare([dateParser]);
expect(
generator.generate(browseMedia, undefined, [dateParser])?.startDate,
).toEqual(expectedDate);
});
it('should fail to generate start date with a date formater without a regexp', async () => {
const dateParser: Parser = {
type: 'startdate',
format: 'yyyy-MM-dd HH:mm',
};
const generator = new MetadataGenerator();
await generator.prepare([dateParser]);
expect(
generator.generate(browseMedia, undefined, [dateParser])?.startDate,
).toBeUndefined();
});
it('should incorporate parent metadata with a date format', async () => {
const parentBrowseMedia = createRichBrowseMedia({
title: '2025-05-26',
_metadata: {
startDate: new Date('2025-05-26T00:00:00.000Z'),
},
});
const childBrowseMedia = createBrowseMedia({
title: '22:42',
});
const parser: Parser = {
type: 'startdate',
format: 'HH:mm',
};
const generator = new MetadataGenerator();
await generator.prepare([parser]);
expect(
generator.generate(childBrowseMedia, parentBrowseMedia, [parser])?.startDate,
).toEqual(new Date('2025-05-26T22:42:00.000Z'));
});
});
});
});
});