refactor(Font): rename fontStore and appliedFontsManager
Both names were vague or overloaded: - fontStore / FontStore -> fontCatalogStore / FontCatalogStore Three font-related stores live in this slice; the new name names the paginated catalog specifically. - appliedFontsManager / AppliedFontsManager -> fontLifecycleManager / FontLifecycleManager "Applied" collided with the filter-side appliedFilterStore (different meaning). The class actually orchestrates a load-use-evict lifecycle with FontBufferCache + FontEvictionPolicy + FontLoadQueue collaborators, so "Manager" is justified. Companion types file moved alongside (appliedFonts.ts -> fontLifecycle.ts). Directories, file basenames, factory (createFontStore -> createFontCatalogStore), and the AppliedFontsManagerDeps interface all renamed. All consumers (ComparisonView, SampleList, FontList, FontApplicator, FontVirtualList, FilterAndSortFonts bindings, createFontRowSizeResolver, mocks) updated.
This commit is contained in:
Ilia Mashkov
@@ -0,0 +1,35 @@
|
||||
/**
|
||||
* Thrown by {@link FontBufferCache} when a font file cannot be retrieved from the network or cache.
|
||||
*
|
||||
* @property url - The URL that was requested.
|
||||
* @property cause - The underlying error, if any.
|
||||
* @property status - HTTP status code. Present on HTTP errors, absent on network failures.
|
||||
*/
|
||||
export class FontFetchError extends Error {
|
||||
readonly name = 'FontFetchError';
|
||||
|
||||
constructor(
|
||||
public readonly url: string,
|
||||
public readonly cause?: unknown,
|
||||
public readonly status?: number,
|
||||
) {
|
||||
super(status ? `HTTP ${status} fetching font: ${url}` : `Network error fetching font: ${url}`);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Thrown by {@link loadFont} when a font buffer cannot be parsed into a {@link FontFace}.
|
||||
*
|
||||
* @property fontName - The display name of the font that failed to parse.
|
||||
* @property cause - The underlying error from the FontFace API.
|
||||
*/
|
||||
export class FontParseError extends Error {
|
||||
readonly name = 'FontParseError';
|
||||
|
||||
constructor(
|
||||
public readonly fontName: string,
|
||||
public readonly cause?: unknown,
|
||||
) {
|
||||
super(`Failed to parse font: ${fontName}`);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,399 @@
|
||||
import { SvelteMap } from 'svelte/reactivity';
|
||||
import {
|
||||
type FontLoadRequestConfig,
|
||||
type FontLoadStatus,
|
||||
} from '../../types';
|
||||
import {
|
||||
FontFetchError,
|
||||
FontParseError,
|
||||
} from './errors';
|
||||
import {
|
||||
generateFontKey,
|
||||
getEffectiveConcurrency,
|
||||
loadFont,
|
||||
yieldToMainThread,
|
||||
} from './utils';
|
||||
import { FontBufferCache } from './utils/fontBufferCache/FontBufferCache';
|
||||
import { FontEvictionPolicy } from './utils/fontEvictionPolicy/FontEvictionPolicy';
|
||||
import { FontLoadQueue } from './utils/fontLoadQueue/FontLoadQueue';
|
||||
|
||||
interface FontLifecycleManagerDeps {
|
||||
cache?: FontBufferCache;
|
||||
eviction?: FontEvictionPolicy;
|
||||
queue?: FontLoadQueue;
|
||||
}
|
||||
|
||||
/**
|
||||
* Manages web font loading with caching, adaptive concurrency, and automatic cleanup.
|
||||
*
|
||||
* **Two-Phase Loading Strategy:**
|
||||
* 1. *Concurrent Fetching*: Font files fetched in parallel (network I/O is non-blocking)
|
||||
* 2. *Sequential Parsing*: Buffers parsed into FontFace objects one at a time with periodic yields
|
||||
*
|
||||
* **Yielding Strategy:**
|
||||
* - Chromium: Yields only when user input is pending (via `scheduler.yield()` + `isInputPending()`)
|
||||
* - Others: Time-based fallback, yields every 8ms
|
||||
*
|
||||
* **Network Adaptation:**
|
||||
* - 2G: 1 concurrent request, 3G: 2, 4G+: 4 (via Network Information API)
|
||||
* - Respects `saveData` mode to defer non-critical weights
|
||||
*
|
||||
* **Cache Integration:** Cache API with best-effort fallback (handles private browsing, quota limits)
|
||||
*
|
||||
* **Cleanup:** LRU-style eviction after 5 minutes of inactivity; cleanup runs every 60 seconds
|
||||
*
|
||||
* **Font Identity:** Variable fonts use `{id}@vf`, static fonts use `{id}@{weight}`
|
||||
*
|
||||
* **Browser APIs Used:** `scheduler.yield()`, `isInputPending()`, `requestIdleCallback`, Cache API, Network Information API
|
||||
*/
|
||||
export class FontLifecycleManager {
|
||||
// Injected collaborators - each handles one concern for better testability
|
||||
readonly #cache: FontBufferCache;
|
||||
readonly #eviction: FontEvictionPolicy;
|
||||
readonly #queue: FontLoadQueue;
|
||||
|
||||
// Loaded FontFace instances registered with document.fonts. Key: `{id}@{weight}` or `{id}@vf`
|
||||
#loadedFonts = new Map<string, FontFace>();
|
||||
|
||||
// Maps font key → URL so #purgeUnused() can evict from cache
|
||||
#urlByKey = new Map<string, string>();
|
||||
|
||||
// Handle for scheduled queue processing (requestIdleCallback or setTimeout)
|
||||
#timeoutId: ReturnType<typeof setTimeout> | null = null;
|
||||
|
||||
// Interval handle for periodic cleanup (runs every PURGE_INTERVAL)
|
||||
#intervalId: ReturnType<typeof setInterval> | null = null;
|
||||
|
||||
// AbortController for canceling in-flight fetches on destroy
|
||||
#abortController = new AbortController();
|
||||
|
||||
// Tracks which callback type is pending ('idle' | 'timeout' | null) for proper cancellation
|
||||
#pendingType: 'idle' | 'timeout' | null = null;
|
||||
|
||||
readonly #PURGE_INTERVAL = 60000;
|
||||
|
||||
// Reactive status map for Svelte components to track font states
|
||||
statuses = new SvelteMap<string, FontLoadStatus>();
|
||||
|
||||
// Starts periodic cleanup timer (browser-only).
|
||||
constructor(
|
||||
{ cache = new FontBufferCache(), eviction = new FontEvictionPolicy(), queue = new FontLoadQueue() }:
|
||||
FontLifecycleManagerDeps = {},
|
||||
) {
|
||||
// Inject collaborators - defaults provided for production, fakes for testing
|
||||
this.#cache = cache;
|
||||
this.#eviction = eviction;
|
||||
this.#queue = queue;
|
||||
if (typeof window !== 'undefined') {
|
||||
this.#intervalId = setInterval(() => this.#purgeUnused(), this.#PURGE_INTERVAL);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Requests fonts to be loaded. Updates usage tracking and queues new fonts.
|
||||
*
|
||||
* Retry behavior: 'loaded' and 'loading' fonts are skipped; 'error' fonts retry if count < MAX_RETRIES.
|
||||
* Scheduling: Prefers requestIdleCallback (150ms timeout), falls back to setTimeout(16ms).
|
||||
*/
|
||||
touch(configs: FontLoadRequestConfig[]) {
|
||||
if (this.#abortController.signal.aborted) {
|
||||
return;
|
||||
}
|
||||
try {
|
||||
const now = Date.now();
|
||||
let hasNewItems = false;
|
||||
|
||||
for (const config of configs) {
|
||||
const key = generateFontKey(config);
|
||||
|
||||
// Update last-used timestamp for LRU eviction policy
|
||||
this.#eviction.touch(key, now);
|
||||
|
||||
const status = this.statuses.get(key);
|
||||
|
||||
// Skip fonts that are already loaded or currently loading
|
||||
if (status === 'loaded' || status === 'loading') {
|
||||
continue;
|
||||
}
|
||||
|
||||
// Skip fonts already in the queue (avoid duplicates)
|
||||
if (this.#queue.has(key)) {
|
||||
continue;
|
||||
}
|
||||
|
||||
// Skip error fonts that have exceeded max retry count
|
||||
if (status === 'error' && this.#queue.isMaxRetriesReached(key)) {
|
||||
continue;
|
||||
}
|
||||
|
||||
// Queue this font for loading
|
||||
this.#queue.enqueue(key, config);
|
||||
hasNewItems = true;
|
||||
}
|
||||
|
||||
if (hasNewItems && !this.#timeoutId) {
|
||||
this.#scheduleProcessing();
|
||||
}
|
||||
} catch (error) {
|
||||
console.error(error);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Schedules `#processQueue()` via `requestIdleCallback` (150ms timeout) when available,
|
||||
* falling back to `setTimeout(16ms)` for ~60fps timing.
|
||||
*/
|
||||
#scheduleProcessing(): void {
|
||||
if (typeof requestIdleCallback !== 'undefined') {
|
||||
this.#timeoutId = requestIdleCallback(
|
||||
() => this.#processQueue(),
|
||||
{ timeout: 150 },
|
||||
) as unknown as ReturnType<typeof setTimeout>;
|
||||
this.#pendingType = 'idle';
|
||||
} else {
|
||||
this.#timeoutId = setTimeout(() => this.#processQueue(), 16);
|
||||
this.#pendingType = 'timeout';
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns true if data-saver mode is enabled (defers non-critical weights).
|
||||
*/
|
||||
#shouldDeferNonCritical(): boolean {
|
||||
return (navigator as any).connection?.saveData === true;
|
||||
}
|
||||
|
||||
/**
|
||||
* Processes queued fonts in two phases:
|
||||
* 1. Concurrent fetching (network I/O, non-blocking)
|
||||
* 2. Sequential parsing with periodic yields (CPU-intensive, can block UI)
|
||||
*
|
||||
* Yielding: Chromium uses `isInputPending()` for optimal responsiveness; others yield every 8ms.
|
||||
*/
|
||||
async #processQueue() {
|
||||
// Clear timer flags since we're now processing
|
||||
this.#timeoutId = null;
|
||||
this.#pendingType = null;
|
||||
|
||||
// Get all queued entries and clear the queue atomically
|
||||
let entries = this.#queue.flush();
|
||||
if (!entries.length) {
|
||||
return;
|
||||
}
|
||||
|
||||
// In data-saver mode, only load variable fonts and common weights (400, 700)
|
||||
if (this.#shouldDeferNonCritical()) {
|
||||
entries = entries.filter(([, c]) => c.isVariable || [400, 700].includes(c.weight));
|
||||
}
|
||||
|
||||
// Determine optimal concurrent fetches based on network speed (1-4)
|
||||
const concurrency = getEffectiveConcurrency();
|
||||
const buffers = new Map<string, ArrayBuffer>();
|
||||
|
||||
// Fetch multiple font files in parallel since network I/O is non-blocking
|
||||
for (let i = 0; i < entries.length; i += concurrency) {
|
||||
await this.#fetchChunk(entries.slice(i, i + concurrency), buffers);
|
||||
}
|
||||
|
||||
// Parse buffers one at a time with periodic yields to avoid blocking UI
|
||||
const hasInputPending = !!(navigator as any).scheduling?.isInputPending;
|
||||
let lastYield = performance.now();
|
||||
const YIELD_INTERVAL = 8;
|
||||
|
||||
for (const [key, config] of entries) {
|
||||
const buffer = buffers.get(key);
|
||||
// Skip fonts that failed to fetch in phase 1
|
||||
if (!buffer) {
|
||||
continue;
|
||||
}
|
||||
|
||||
await this.#processFont(key, config, buffer);
|
||||
|
||||
// Yield to main thread if needed (prevents UI blocking)
|
||||
// Chromium: use isInputPending() for optimal responsiveness
|
||||
// Others: yield every 8ms as fallback
|
||||
const shouldYield = hasInputPending
|
||||
? (navigator as any).scheduling.isInputPending({ includeContinuous: true })
|
||||
: performance.now() - lastYield > YIELD_INTERVAL;
|
||||
|
||||
if (shouldYield) {
|
||||
await yieldToMainThread();
|
||||
lastYield = performance.now();
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Fetches a chunk of fonts concurrently and populates `buffers` with successful results.
|
||||
* Each promise carries its own key and config so results need no index correlation.
|
||||
* Aborted fetches are silently skipped; other errors set status to `'error'` and increment retry.
|
||||
*/
|
||||
async #fetchChunk(
|
||||
chunk: Array<[string, FontLoadRequestConfig]>,
|
||||
buffers: Map<string, ArrayBuffer>,
|
||||
): Promise<void> {
|
||||
const results = await Promise.all(
|
||||
chunk.map(async ([key, config]) => {
|
||||
this.statuses.set(key, 'loading');
|
||||
try {
|
||||
const buffer = await this.#cache.get(config.url, this.#abortController.signal);
|
||||
buffers.set(key, buffer);
|
||||
return { ok: true as const, key };
|
||||
} catch (reason) {
|
||||
return { ok: false as const, key, config, reason };
|
||||
}
|
||||
}),
|
||||
);
|
||||
|
||||
for (const result of results) {
|
||||
if (result.ok) {
|
||||
continue;
|
||||
}
|
||||
const { key, config, reason } = result;
|
||||
const isAbort = reason instanceof FontFetchError
|
||||
&& reason.cause instanceof Error
|
||||
&& reason.cause.name === 'AbortError';
|
||||
if (isAbort) {
|
||||
continue;
|
||||
}
|
||||
if (reason instanceof FontFetchError) {
|
||||
console.error(`Font fetch failed: ${config.name}`, reason);
|
||||
}
|
||||
this.statuses.set(key, 'error');
|
||||
this.#queue.incrementRetry(key);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Parses a fetched buffer into a {@link FontFace}, registers it with `document.fonts`,
|
||||
* and updates reactive status. On failure, sets status to `'error'` and increments the retry count.
|
||||
*/
|
||||
async #processFont(key: string, config: FontLoadRequestConfig, buffer: ArrayBuffer): Promise<void> {
|
||||
try {
|
||||
const font = await loadFont(config, buffer);
|
||||
this.#loadedFonts.set(key, font);
|
||||
this.#urlByKey.set(key, config.url);
|
||||
this.statuses.set(key, 'loaded');
|
||||
} catch (e) {
|
||||
if (e instanceof FontParseError) {
|
||||
console.error(`Font parse failed: ${config.name}`, e);
|
||||
this.statuses.set(key, 'error');
|
||||
this.#queue.incrementRetry(key);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Removes fonts unused within TTL (LRU-style cleanup). Runs every PURGE_INTERVAL. Pinned fonts are never evicted.
|
||||
*/
|
||||
#purgeUnused() {
|
||||
const now = Date.now();
|
||||
// Iterate through all tracked font keys
|
||||
for (const key of this.#eviction.keys()) {
|
||||
// Skip fonts that are still within TTL or are pinned
|
||||
if (!this.#eviction.shouldEvict(key, now)) {
|
||||
continue;
|
||||
}
|
||||
|
||||
// Remove FontFace from document to free memory
|
||||
const font = this.#loadedFonts.get(key);
|
||||
if (font) {
|
||||
document.fonts.delete(font);
|
||||
}
|
||||
|
||||
// Evict from cache and cleanup URL mapping
|
||||
const url = this.#urlByKey.get(key);
|
||||
if (url) {
|
||||
this.#cache.evict(url);
|
||||
this.#urlByKey.delete(key);
|
||||
}
|
||||
|
||||
// Clean up remaining state
|
||||
this.#loadedFonts.delete(key);
|
||||
this.statuses.delete(key);
|
||||
this.#eviction.remove(key);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns current loading status for a font, or undefined if never requested.
|
||||
*/
|
||||
getFontStatus(id: string, weight: number, isVariable = false) {
|
||||
try {
|
||||
return this.statuses.get(generateFontKey({ id, weight, isVariable }));
|
||||
} catch (error) {
|
||||
console.error(error);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Pins a font so it is never evicted by #purgeUnused(), regardless of TTL.
|
||||
*/
|
||||
pin(id: string, weight: number, isVariable = false): void {
|
||||
this.#eviction.pin(generateFontKey({ id, weight, isVariable }));
|
||||
}
|
||||
|
||||
/**
|
||||
* Unpins a font, allowing it to be evicted by #purgeUnused() once its TTL expires.
|
||||
*/
|
||||
unpin(id: string, weight: number, isVariable = false): void {
|
||||
this.#eviction.unpin(generateFontKey({ id, weight, isVariable }));
|
||||
}
|
||||
|
||||
/**
|
||||
* Waits for all fonts to finish loading using document.fonts.ready.
|
||||
*/
|
||||
async ready(): Promise<void> {
|
||||
if (typeof document === 'undefined') {
|
||||
return;
|
||||
}
|
||||
try {
|
||||
await document.fonts.ready;
|
||||
} catch { /* document unloaded */ }
|
||||
}
|
||||
|
||||
/**
|
||||
* Aborts all operations, removes fonts from document, and clears state. Manager cannot be reused after.
|
||||
*/
|
||||
destroy() {
|
||||
// Abort all in-flight network requests
|
||||
this.#abortController.abort();
|
||||
|
||||
// Cancel pending queue processing (idle callback or timeout)
|
||||
if (this.#timeoutId !== null) {
|
||||
if (this.#pendingType === 'idle' && typeof cancelIdleCallback !== 'undefined') {
|
||||
cancelIdleCallback(this.#timeoutId as unknown as number);
|
||||
} else {
|
||||
clearTimeout(this.#timeoutId);
|
||||
}
|
||||
this.#timeoutId = null;
|
||||
this.#pendingType = null;
|
||||
}
|
||||
|
||||
// Stop periodic cleanup timer
|
||||
if (this.#intervalId) {
|
||||
clearInterval(this.#intervalId);
|
||||
this.#intervalId = null;
|
||||
}
|
||||
|
||||
// Remove all loaded fonts from document
|
||||
if (typeof document !== 'undefined') {
|
||||
for (const font of this.#loadedFonts.values()) {
|
||||
document.fonts.delete(font);
|
||||
}
|
||||
}
|
||||
|
||||
// Clear all state and collaborators
|
||||
this.#loadedFonts.clear();
|
||||
this.#urlByKey.clear();
|
||||
this.#cache.clear();
|
||||
this.#eviction.clear();
|
||||
this.#queue.clear();
|
||||
this.statuses.clear();
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Singleton instance — use throughout the application for unified font loading state.
|
||||
*/
|
||||
export const fontLifecycleManager = new FontLifecycleManager();
|
||||
@@ -0,0 +1,318 @@
|
||||
/**
|
||||
* @vitest-environment jsdom
|
||||
*/
|
||||
import { FontFetchError } from './errors';
|
||||
import { FontLifecycleManager } from './fontLifecycleManager.svelte';
|
||||
import { FontEvictionPolicy } from './utils/fontEvictionPolicy/FontEvictionPolicy';
|
||||
|
||||
class FakeBufferCache {
|
||||
async get(_url: string): Promise<ArrayBuffer> {
|
||||
return new ArrayBuffer(8);
|
||||
}
|
||||
evict(_url: string): void {}
|
||||
clear(): void {}
|
||||
}
|
||||
|
||||
/**
|
||||
* Throws {@link FontFetchError} on every `get()` — simulates network/HTTP failure.
|
||||
*/
|
||||
class FailingBufferCache {
|
||||
async get(url: string): Promise<never> {
|
||||
throw new FontFetchError(url, new Error('network error'), 500);
|
||||
}
|
||||
evict(_url: string): void {}
|
||||
clear(): void {}
|
||||
}
|
||||
|
||||
const makeConfig = (id: string, overrides: Partial<{ weight: number; isVariable: boolean }> = {}) => ({
|
||||
id,
|
||||
name: id,
|
||||
url: `https://example.com/${id}.woff2`,
|
||||
weight: 400,
|
||||
...overrides,
|
||||
});
|
||||
|
||||
describe('FontLifecycleManager', () => {
|
||||
let manager: FontLifecycleManager;
|
||||
let eviction: FontEvictionPolicy;
|
||||
let mockFontFaceSet: { add: ReturnType<typeof vi.fn>; delete: ReturnType<typeof vi.fn> };
|
||||
|
||||
beforeEach(() => {
|
||||
vi.useFakeTimers();
|
||||
eviction = new FontEvictionPolicy({ ttl: 60000 });
|
||||
mockFontFaceSet = { add: vi.fn(), delete: vi.fn() };
|
||||
|
||||
Object.defineProperty(document, 'fonts', {
|
||||
value: mockFontFaceSet,
|
||||
configurable: true,
|
||||
writable: true,
|
||||
});
|
||||
|
||||
const MockFontFace = vi.fn(function(this: any, name: string, buffer: BufferSource) {
|
||||
this.name = name;
|
||||
this.buffer = buffer;
|
||||
this.load = vi.fn().mockResolvedValue(this);
|
||||
});
|
||||
vi.stubGlobal('FontFace', MockFontFace);
|
||||
|
||||
manager = new FontLifecycleManager({ cache: new FakeBufferCache() as any, eviction });
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
vi.clearAllTimers();
|
||||
vi.useRealTimers();
|
||||
vi.unstubAllGlobals();
|
||||
});
|
||||
|
||||
describe('touch()', () => {
|
||||
it('queues and loads a new font', async () => {
|
||||
manager.touch([makeConfig('roboto')]);
|
||||
await vi.advanceTimersByTimeAsync(50);
|
||||
|
||||
expect(manager.getFontStatus('roboto', 400)).toBe('loaded');
|
||||
});
|
||||
|
||||
it('batches multiple fonts into a single queue flush', async () => {
|
||||
manager.touch([makeConfig('lato'), makeConfig('inter')]);
|
||||
await vi.advanceTimersByTimeAsync(50);
|
||||
|
||||
expect(mockFontFaceSet.add).toHaveBeenCalledTimes(2);
|
||||
});
|
||||
|
||||
it('skips fonts that are already loaded', async () => {
|
||||
manager.touch([makeConfig('lato')]);
|
||||
await vi.advanceTimersByTimeAsync(50);
|
||||
|
||||
manager.touch([makeConfig('lato')]);
|
||||
await vi.advanceTimersByTimeAsync(50);
|
||||
|
||||
expect(mockFontFaceSet.add).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
it('skips fonts that are currently loading', async () => {
|
||||
manager.touch([makeConfig('lato')]);
|
||||
// simulate loading state before queue drains
|
||||
manager.statuses.set('lato@400', 'loading');
|
||||
manager.touch([makeConfig('lato')]);
|
||||
await vi.advanceTimersByTimeAsync(50);
|
||||
|
||||
expect(mockFontFaceSet.add).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
it('skips fonts that have exhausted retries', async () => {
|
||||
const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
|
||||
const failManager = new FontLifecycleManager({ cache: new FailingBufferCache() as any, eviction });
|
||||
|
||||
// exhaust all 3 retries
|
||||
for (let i = 0; i < 3; i++) {
|
||||
failManager.statuses.delete('broken@400');
|
||||
failManager.touch([makeConfig('broken')]);
|
||||
await vi.advanceTimersByTimeAsync(50);
|
||||
}
|
||||
|
||||
failManager.touch([makeConfig('broken')]);
|
||||
await vi.advanceTimersByTimeAsync(50);
|
||||
|
||||
expect(failManager.getFontStatus('broken', 400)).toBe('error');
|
||||
expect(mockFontFaceSet.add).not.toHaveBeenCalled();
|
||||
consoleSpy.mockRestore();
|
||||
});
|
||||
|
||||
it('does nothing after manager is destroyed', async () => {
|
||||
manager.destroy();
|
||||
manager.touch([makeConfig('roboto')]);
|
||||
await vi.advanceTimersByTimeAsync(50);
|
||||
|
||||
expect(manager.statuses.size).toBe(0);
|
||||
});
|
||||
});
|
||||
|
||||
describe('queue processing', () => {
|
||||
it('filters non-critical weights in data-saver mode', async () => {
|
||||
(navigator as any).connection = { saveData: true };
|
||||
|
||||
manager.touch([
|
||||
makeConfig('light', { weight: 300 }),
|
||||
makeConfig('regular', { weight: 400 }),
|
||||
makeConfig('bold', { weight: 700 }),
|
||||
]);
|
||||
await vi.advanceTimersByTimeAsync(50);
|
||||
|
||||
expect(manager.getFontStatus('light', 300)).toBeUndefined();
|
||||
expect(manager.getFontStatus('regular', 400)).toBe('loaded');
|
||||
expect(manager.getFontStatus('bold', 700)).toBe('loaded');
|
||||
|
||||
delete (navigator as any).connection;
|
||||
});
|
||||
|
||||
it('loads variable fonts in data-saver mode regardless of weight', async () => {
|
||||
(navigator as any).connection = { saveData: true };
|
||||
|
||||
manager.touch([makeConfig('vf', { weight: 300, isVariable: true })]);
|
||||
await vi.advanceTimersByTimeAsync(50);
|
||||
|
||||
expect(manager.getFontStatus('vf', 300, true)).toBe('loaded');
|
||||
|
||||
delete (navigator as any).connection;
|
||||
});
|
||||
});
|
||||
|
||||
describe('Phase 1 — fetch', () => {
|
||||
it('sets status to error on fetch failure', async () => {
|
||||
const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
|
||||
const failManager = new FontLifecycleManager({ cache: new FailingBufferCache() as any, eviction });
|
||||
|
||||
failManager.touch([makeConfig('broken')]);
|
||||
await vi.advanceTimersByTimeAsync(50);
|
||||
|
||||
expect(failManager.getFontStatus('broken', 400)).toBe('error');
|
||||
consoleSpy.mockRestore();
|
||||
});
|
||||
|
||||
it('logs a console error on fetch failure', async () => {
|
||||
const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
|
||||
const failManager = new FontLifecycleManager({ cache: new FailingBufferCache() as any, eviction });
|
||||
|
||||
failManager.touch([makeConfig('broken')]);
|
||||
await vi.advanceTimersByTimeAsync(50);
|
||||
|
||||
expect(consoleSpy).toHaveBeenCalled();
|
||||
consoleSpy.mockRestore();
|
||||
});
|
||||
|
||||
it('does not set error status or log for aborted fetches', async () => {
|
||||
const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
|
||||
const abortingCache = {
|
||||
async get(url: string): Promise<never> {
|
||||
throw new FontFetchError(url, Object.assign(new Error('Aborted'), { name: 'AbortError' }));
|
||||
},
|
||||
evict() {},
|
||||
clear() {},
|
||||
};
|
||||
const abortManager = new FontLifecycleManager({ cache: abortingCache as any, eviction });
|
||||
|
||||
abortManager.touch([makeConfig('aborted')]);
|
||||
await vi.advanceTimersByTimeAsync(50);
|
||||
|
||||
// status is left as 'loading' (not 'error') — abort is not a retriable failure
|
||||
expect(abortManager.getFontStatus('aborted', 400)).not.toBe('error');
|
||||
expect(consoleSpy).not.toHaveBeenCalled();
|
||||
consoleSpy.mockRestore();
|
||||
});
|
||||
});
|
||||
|
||||
describe('Phase 2 — parse', () => {
|
||||
it('sets status to error on parse failure', async () => {
|
||||
const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
|
||||
const FailingFontFace = vi.fn(function(this: any) {
|
||||
this.load = vi.fn().mockRejectedValue(new Error('parse failed'));
|
||||
});
|
||||
vi.stubGlobal('FontFace', FailingFontFace);
|
||||
|
||||
manager.touch([makeConfig('broken')]);
|
||||
await vi.advanceTimersByTimeAsync(50);
|
||||
|
||||
expect(manager.getFontStatus('broken', 400)).toBe('error');
|
||||
consoleSpy.mockRestore();
|
||||
});
|
||||
|
||||
it('logs a console error on parse failure', async () => {
|
||||
const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
|
||||
const FailingFontFace = vi.fn(function(this: any) {
|
||||
this.load = vi.fn().mockRejectedValue(new Error('parse failed'));
|
||||
});
|
||||
vi.stubGlobal('FontFace', FailingFontFace);
|
||||
|
||||
manager.touch([makeConfig('broken')]);
|
||||
await vi.advanceTimersByTimeAsync(50);
|
||||
|
||||
expect(consoleSpy).toHaveBeenCalled();
|
||||
consoleSpy.mockRestore();
|
||||
});
|
||||
});
|
||||
|
||||
describe('#purgeUnused', () => {
|
||||
it('evicts fonts after TTL expires', async () => {
|
||||
manager.touch([makeConfig('ephemeral')]);
|
||||
await vi.advanceTimersByTimeAsync(50);
|
||||
|
||||
await vi.advanceTimersByTimeAsync(61000);
|
||||
|
||||
expect(manager.getFontStatus('ephemeral', 400)).toBeUndefined();
|
||||
expect(mockFontFaceSet.delete).toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('removes the evicted key from the eviction policy', async () => {
|
||||
manager.touch([makeConfig('ephemeral')]);
|
||||
await vi.advanceTimersByTimeAsync(50);
|
||||
|
||||
await vi.advanceTimersByTimeAsync(61000);
|
||||
|
||||
expect(Array.from(eviction.keys())).not.toContain('ephemeral@400');
|
||||
});
|
||||
|
||||
it('refreshes TTL when font is re-touched before expiry', async () => {
|
||||
const config = makeConfig('active');
|
||||
manager.touch([config]);
|
||||
await vi.advanceTimersByTimeAsync(50);
|
||||
|
||||
await vi.advanceTimersByTimeAsync(40000);
|
||||
manager.touch([config]); // refresh at t≈40s
|
||||
|
||||
await vi.advanceTimersByTimeAsync(25000); // purge at t≈60s sees only ~20s elapsed → not evicted
|
||||
|
||||
expect(manager.getFontStatus('active', 400)).toBe('loaded');
|
||||
});
|
||||
|
||||
it('does not evict pinned fonts', async () => {
|
||||
manager.touch([makeConfig('pinned')]);
|
||||
await vi.advanceTimersByTimeAsync(50);
|
||||
|
||||
manager.pin('pinned', 400);
|
||||
await vi.advanceTimersByTimeAsync(61000);
|
||||
|
||||
expect(manager.getFontStatus('pinned', 400)).toBe('loaded');
|
||||
expect(mockFontFaceSet.delete).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('evicts font after it is unpinned and TTL expires', async () => {
|
||||
manager.touch([makeConfig('toggled')]);
|
||||
await vi.advanceTimersByTimeAsync(50);
|
||||
|
||||
manager.pin('toggled', 400);
|
||||
manager.unpin('toggled', 400);
|
||||
await vi.advanceTimersByTimeAsync(61000);
|
||||
|
||||
expect(manager.getFontStatus('toggled', 400)).toBeUndefined();
|
||||
expect(mockFontFaceSet.delete).toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
describe('destroy()', () => {
|
||||
it('clears all statuses', async () => {
|
||||
manager.touch([makeConfig('roboto')]);
|
||||
await vi.advanceTimersByTimeAsync(50);
|
||||
|
||||
manager.destroy();
|
||||
|
||||
expect(manager.statuses.size).toBe(0);
|
||||
});
|
||||
|
||||
it('removes all loaded fonts from document.fonts', async () => {
|
||||
manager.touch([makeConfig('roboto'), makeConfig('inter')]);
|
||||
await vi.advanceTimersByTimeAsync(50);
|
||||
|
||||
manager.destroy();
|
||||
|
||||
expect(mockFontFaceSet.delete).toHaveBeenCalledTimes(2);
|
||||
});
|
||||
|
||||
it('prevents further loading after destroy', async () => {
|
||||
manager.destroy();
|
||||
manager.touch([makeConfig('roboto')]);
|
||||
await vi.advanceTimersByTimeAsync(50);
|
||||
|
||||
expect(manager.statuses.size).toBe(0);
|
||||
});
|
||||
});
|
||||
});
|
||||
+68
@@ -0,0 +1,68 @@
|
||||
/**
|
||||
* @vitest-environment jsdom
|
||||
*/
|
||||
import { FontFetchError } from '../../errors';
|
||||
import { FontBufferCache } from './FontBufferCache';
|
||||
|
||||
const makeBuffer = () => new ArrayBuffer(8);
|
||||
|
||||
const makeFetcher = (overrides: Partial<Response> = {}) =>
|
||||
vi.fn().mockResolvedValue({
|
||||
ok: true,
|
||||
status: 200,
|
||||
arrayBuffer: () => Promise.resolve(makeBuffer()),
|
||||
clone: () => ({ ok: true, status: 200, arrayBuffer: () => Promise.resolve(makeBuffer()) }),
|
||||
...overrides,
|
||||
} as Response);
|
||||
|
||||
describe('FontBufferCache', () => {
|
||||
let cache: FontBufferCache;
|
||||
let fetcher: ReturnType<typeof makeFetcher>;
|
||||
|
||||
beforeEach(() => {
|
||||
fetcher = makeFetcher();
|
||||
cache = new FontBufferCache({ fetcher });
|
||||
});
|
||||
|
||||
it('returns buffer from memory on second call without fetching', async () => {
|
||||
await cache.get('https://example.com/font.woff2');
|
||||
await cache.get('https://example.com/font.woff2');
|
||||
|
||||
expect(fetcher).toHaveBeenCalledOnce();
|
||||
});
|
||||
|
||||
it('throws FontFetchError on HTTP error with correct status', async () => {
|
||||
const errorFetcher = makeFetcher({ ok: false, status: 404 });
|
||||
const errorCache = new FontBufferCache({ fetcher: errorFetcher });
|
||||
|
||||
const err = await errorCache.get('https://example.com/font.woff2').catch(e => e);
|
||||
expect(err).toBeInstanceOf(FontFetchError);
|
||||
expect(err.status).toBe(404);
|
||||
});
|
||||
|
||||
it('throws FontFetchError on network failure without status', async () => {
|
||||
const networkFetcher = vi.fn().mockRejectedValue(new Error('network down'));
|
||||
const networkCache = new FontBufferCache({ fetcher: networkFetcher });
|
||||
|
||||
const err = await networkCache.get('https://example.com/font.woff2').catch(e => e);
|
||||
expect(err).toBeInstanceOf(FontFetchError);
|
||||
expect(err.status).toBeUndefined();
|
||||
});
|
||||
|
||||
it('evict removes url from memory so next call fetches again', async () => {
|
||||
await cache.get('https://example.com/font.woff2');
|
||||
cache.evict('https://example.com/font.woff2');
|
||||
await cache.get('https://example.com/font.woff2');
|
||||
|
||||
expect(fetcher).toHaveBeenCalledTimes(2);
|
||||
});
|
||||
|
||||
it('clear wipes all memory cache entries', async () => {
|
||||
await cache.get('https://example.com/a.woff2');
|
||||
await cache.get('https://example.com/b.woff2');
|
||||
cache.clear();
|
||||
await cache.get('https://example.com/a.woff2');
|
||||
|
||||
expect(fetcher).toHaveBeenCalledTimes(3);
|
||||
});
|
||||
});
|
||||
+105
@@ -0,0 +1,105 @@
|
||||
import { FontFetchError } from '../../errors';
|
||||
|
||||
type Fetcher = (url: string, init?: RequestInit) => Promise<Response>;
|
||||
|
||||
interface FontBufferCacheOptions {
|
||||
/**
|
||||
* Custom fetch implementation. Defaults to `globalThis.fetch`. Inject in tests for isolation.
|
||||
*/
|
||||
fetcher?: Fetcher;
|
||||
/**
|
||||
* Cache API cache name. Defaults to `'font-cache-v1'`.
|
||||
*/
|
||||
cacheName?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Three-tier font buffer cache: in-memory → Cache API → network.
|
||||
*
|
||||
* - **Tier 1 (memory):** Fastest — no I/O. Populated after first successful fetch.
|
||||
* - **Tier 2 (Cache API):** Persists across page loads. Silently skipped in private browsing.
|
||||
* - **Tier 3 (network):** Raw fetch. Throws {@link FontFetchError} on failure.
|
||||
*
|
||||
* The `fetcher` option is injectable for testing — pass a `vi.fn()` to avoid real network calls.
|
||||
*/
|
||||
export class FontBufferCache {
|
||||
#buffersByUrl = new Map<string, ArrayBuffer>();
|
||||
|
||||
readonly #fetcher: Fetcher;
|
||||
readonly #cacheName: string;
|
||||
|
||||
constructor(
|
||||
{ fetcher = globalThis.fetch.bind(globalThis), cacheName = 'font-cache-v1' }: FontBufferCacheOptions = {},
|
||||
) {
|
||||
this.#fetcher = fetcher;
|
||||
this.#cacheName = cacheName;
|
||||
}
|
||||
|
||||
/**
|
||||
* Retrieves the font buffer for the given URL using the three-tier strategy.
|
||||
* Stores the result in memory on success.
|
||||
*
|
||||
* @throws {@link FontFetchError} if the network request fails or returns a non-OK response.
|
||||
*/
|
||||
async get(url: string, signal?: AbortSignal): Promise<ArrayBuffer> {
|
||||
// Tier 1: in-memory (fastest, no I/O)
|
||||
const inMemory = this.#buffersByUrl.get(url);
|
||||
if (inMemory) {
|
||||
return inMemory;
|
||||
}
|
||||
|
||||
// Tier 2: Cache API
|
||||
try {
|
||||
if (typeof caches !== 'undefined') {
|
||||
const cache = await caches.open(this.#cacheName);
|
||||
const cached = await cache.match(url);
|
||||
if (cached) {
|
||||
const buffer = await cached.arrayBuffer();
|
||||
this.#buffersByUrl.set(url, buffer);
|
||||
return buffer;
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
// Cache unavailable (private browsing, security restrictions) — fall through to network
|
||||
}
|
||||
|
||||
// Tier 3: network
|
||||
let response: Response;
|
||||
try {
|
||||
response = await this.#fetcher(url, { signal });
|
||||
} catch (cause) {
|
||||
throw new FontFetchError(url, cause);
|
||||
}
|
||||
|
||||
if (!response.ok) {
|
||||
throw new FontFetchError(url, undefined, response.status);
|
||||
}
|
||||
|
||||
try {
|
||||
if (typeof caches !== 'undefined') {
|
||||
const cache = await caches.open(this.#cacheName);
|
||||
await cache.put(url, response.clone());
|
||||
}
|
||||
} catch {
|
||||
// Cache write failed (quota, storage pressure) — return font anyway
|
||||
}
|
||||
|
||||
const buffer = await response.arrayBuffer();
|
||||
this.#buffersByUrl.set(url, buffer);
|
||||
return buffer;
|
||||
}
|
||||
|
||||
/**
|
||||
* Removes a URL from the in-memory cache. Next call to `get()` will re-fetch.
|
||||
*/
|
||||
evict(url: string): void {
|
||||
this.#buffersByUrl.delete(url);
|
||||
}
|
||||
|
||||
/**
|
||||
* Clears all in-memory cached buffers.
|
||||
*/
|
||||
clear(): void {
|
||||
this.#buffersByUrl.clear();
|
||||
}
|
||||
}
|
||||
+69
@@ -0,0 +1,69 @@
|
||||
import { FontEvictionPolicy } from './FontEvictionPolicy';
|
||||
|
||||
describe('FontEvictionPolicy', () => {
|
||||
let policy: FontEvictionPolicy;
|
||||
const TTL = 1000;
|
||||
const t0 = 100000;
|
||||
|
||||
beforeEach(() => {
|
||||
policy = new FontEvictionPolicy({ ttl: TTL });
|
||||
});
|
||||
|
||||
it('shouldEvict returns false within TTL', () => {
|
||||
policy.touch('a@400', t0);
|
||||
expect(policy.shouldEvict('a@400', t0 + TTL - 1)).toBe(false);
|
||||
});
|
||||
|
||||
it('shouldEvict returns true at TTL boundary', () => {
|
||||
policy.touch('a@400', t0);
|
||||
expect(policy.shouldEvict('a@400', t0 + TTL)).toBe(true);
|
||||
});
|
||||
|
||||
it('shouldEvict returns false for pinned key regardless of TTL', () => {
|
||||
policy.touch('a@400', t0);
|
||||
policy.pin('a@400');
|
||||
expect(policy.shouldEvict('a@400', t0 + TTL * 10)).toBe(false);
|
||||
});
|
||||
|
||||
it('shouldEvict returns true again after unpin past TTL', () => {
|
||||
policy.touch('a@400', t0);
|
||||
policy.pin('a@400');
|
||||
policy.unpin('a@400');
|
||||
expect(policy.shouldEvict('a@400', t0 + TTL)).toBe(true);
|
||||
});
|
||||
|
||||
it('shouldEvict returns false for untracked key', () => {
|
||||
expect(policy.shouldEvict('never@touched', t0 + TTL * 100)).toBe(false);
|
||||
});
|
||||
|
||||
it('keys returns all tracked keys', () => {
|
||||
policy.touch('a@400', t0);
|
||||
policy.touch('b@vf', t0);
|
||||
expect(Array.from(policy.keys())).toEqual(expect.arrayContaining(['a@400', 'b@vf']));
|
||||
});
|
||||
|
||||
it('remove deletes key from tracking so it no longer appears in keys()', () => {
|
||||
policy.touch('a@400', t0);
|
||||
policy.touch('b@vf', t0);
|
||||
policy.remove('a@400');
|
||||
expect(Array.from(policy.keys())).not.toContain('a@400');
|
||||
expect(Array.from(policy.keys())).toContain('b@vf');
|
||||
});
|
||||
|
||||
it('remove unpins the key so a subsequent touch + TTL would evict it', () => {
|
||||
policy.touch('a@400', t0);
|
||||
policy.pin('a@400');
|
||||
policy.remove('a@400');
|
||||
// re-touch and check it can be evicted again
|
||||
policy.touch('a@400', t0);
|
||||
expect(policy.shouldEvict('a@400', t0 + TTL)).toBe(true);
|
||||
});
|
||||
|
||||
it('clear resets all state', () => {
|
||||
policy.touch('a@400', t0);
|
||||
policy.pin('a@400');
|
||||
policy.clear();
|
||||
expect(Array.from(policy.keys())).toHaveLength(0);
|
||||
expect(policy.shouldEvict('a@400', t0 + TTL * 10)).toBe(false);
|
||||
});
|
||||
});
|
||||
+88
@@ -0,0 +1,88 @@
|
||||
interface FontEvictionPolicyOptions {
|
||||
/**
|
||||
* TTL in milliseconds. Defaults to 5 minutes.
|
||||
*/
|
||||
ttl?: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Tracks font usage timestamps and pinned keys to determine when a font should be evicted.
|
||||
*
|
||||
* Pure data — no browser APIs. Accepts explicit `now` timestamps so tests
|
||||
* never need fake timers.
|
||||
*/
|
||||
export class FontEvictionPolicy {
|
||||
#usageTracker = new Map<string, number>();
|
||||
#pinnedFonts = new Set<string>();
|
||||
|
||||
readonly #TTL: number;
|
||||
|
||||
constructor({ ttl = 5 * 60 * 1000 }: FontEvictionPolicyOptions = {}) {
|
||||
this.#TTL = ttl;
|
||||
}
|
||||
|
||||
/**
|
||||
* Records the last-used time for a font key.
|
||||
* @param key - Font key in `{id}@{weight}` or `{id}@vf` format.
|
||||
* @param now - Current timestamp in ms. Defaults to `Date.now()`.
|
||||
*/
|
||||
touch(key: string, now: number = Date.now()): void {
|
||||
this.#usageTracker.set(key, now);
|
||||
}
|
||||
|
||||
/**
|
||||
* Pins a font key so it is never evicted regardless of TTL.
|
||||
*/
|
||||
pin(key: string): void {
|
||||
this.#pinnedFonts.add(key);
|
||||
}
|
||||
|
||||
/**
|
||||
* Unpins a font key, allowing it to be evicted once its TTL expires.
|
||||
*/
|
||||
unpin(key: string): void {
|
||||
this.#pinnedFonts.delete(key);
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns `true` if the font should be evicted.
|
||||
* A font is evicted when its TTL has elapsed and it is not pinned.
|
||||
* Returns `false` for untracked keys.
|
||||
*
|
||||
* @param key - Font key to check.
|
||||
* @param now - Current timestamp in ms (pass explicitly for deterministic tests).
|
||||
*/
|
||||
shouldEvict(key: string, now: number): boolean {
|
||||
const lastUsed = this.#usageTracker.get(key);
|
||||
if (lastUsed === undefined) {
|
||||
return false;
|
||||
}
|
||||
if (this.#pinnedFonts.has(key)) {
|
||||
return false;
|
||||
}
|
||||
return now - lastUsed >= this.#TTL;
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns an iterator over all tracked font keys.
|
||||
*/
|
||||
keys(): IterableIterator<string> {
|
||||
return this.#usageTracker.keys();
|
||||
}
|
||||
|
||||
/**
|
||||
* Removes a font key from tracking. Called by the orchestrator after eviction.
|
||||
*/
|
||||
remove(key: string): void {
|
||||
this.#usageTracker.delete(key);
|
||||
this.#pinnedFonts.delete(key);
|
||||
}
|
||||
|
||||
/**
|
||||
* Clears all usage timestamps and pinned keys.
|
||||
*/
|
||||
clear(): void {
|
||||
this.#usageTracker.clear();
|
||||
this.#pinnedFonts.clear();
|
||||
}
|
||||
}
|
||||
+65
@@ -0,0 +1,65 @@
|
||||
import type { FontLoadRequestConfig } from '../../../../types';
|
||||
import { FontLoadQueue } from './FontLoadQueue';
|
||||
|
||||
const config = (id: string): FontLoadRequestConfig => ({
|
||||
id,
|
||||
name: id,
|
||||
url: `https://example.com/${id}.woff2`,
|
||||
weight: 400,
|
||||
});
|
||||
|
||||
describe('FontLoadQueue', () => {
|
||||
let queue: FontLoadQueue;
|
||||
|
||||
beforeEach(() => {
|
||||
queue = new FontLoadQueue();
|
||||
});
|
||||
|
||||
it('enqueue returns true for a new key', () => {
|
||||
expect(queue.enqueue('a@400', config('a'))).toBe(true);
|
||||
});
|
||||
|
||||
it('enqueue returns false for an already-queued key', () => {
|
||||
queue.enqueue('a@400', config('a'));
|
||||
expect(queue.enqueue('a@400', config('a'))).toBe(false);
|
||||
});
|
||||
|
||||
it('has returns true after enqueue, false after flush', () => {
|
||||
queue.enqueue('a@400', config('a'));
|
||||
expect(queue.has('a@400')).toBe(true);
|
||||
queue.flush();
|
||||
expect(queue.has('a@400')).toBe(false);
|
||||
});
|
||||
|
||||
it('flush returns all entries and atomically clears the queue', () => {
|
||||
queue.enqueue('a@400', config('a'));
|
||||
queue.enqueue('b@700', config('b'));
|
||||
const entries = queue.flush();
|
||||
expect(entries).toHaveLength(2);
|
||||
expect(queue.has('a@400')).toBe(false);
|
||||
expect(queue.has('b@700')).toBe(false);
|
||||
});
|
||||
|
||||
it('isMaxRetriesReached returns false below MAX_RETRIES', () => {
|
||||
queue.incrementRetry('a@400');
|
||||
queue.incrementRetry('a@400');
|
||||
expect(queue.isMaxRetriesReached('a@400')).toBe(false);
|
||||
});
|
||||
|
||||
it('isMaxRetriesReached returns true at MAX_RETRIES (3)', () => {
|
||||
queue.incrementRetry('a@400');
|
||||
queue.incrementRetry('a@400');
|
||||
queue.incrementRetry('a@400');
|
||||
expect(queue.isMaxRetriesReached('a@400')).toBe(true);
|
||||
});
|
||||
|
||||
it('clear resets queue and retry counts', () => {
|
||||
queue.enqueue('a@400', config('a'));
|
||||
queue.incrementRetry('a@400');
|
||||
queue.incrementRetry('a@400');
|
||||
queue.incrementRetry('a@400');
|
||||
queue.clear();
|
||||
expect(queue.has('a@400')).toBe(false);
|
||||
expect(queue.isMaxRetriesReached('a@400')).toBe(false);
|
||||
});
|
||||
});
|
||||
+65
@@ -0,0 +1,65 @@
|
||||
import type { FontLoadRequestConfig } from '../../../../types';
|
||||
|
||||
/**
|
||||
* Manages the font load queue and per-font retry counts.
|
||||
*
|
||||
* Scheduling (when to drain the queue) is handled by the orchestrator —
|
||||
* this class is purely concerned with what is queued and whether retries are exhausted.
|
||||
*/
|
||||
export class FontLoadQueue {
|
||||
#queue = new Map<string, FontLoadRequestConfig>();
|
||||
#retryCounts = new Map<string, number>();
|
||||
|
||||
readonly #MAX_RETRIES = 3;
|
||||
|
||||
/**
|
||||
* Adds a font to the queue.
|
||||
* @returns `true` if the key was newly enqueued, `false` if it was already present.
|
||||
*/
|
||||
enqueue(key: string, config: FontLoadRequestConfig): boolean {
|
||||
if (this.#queue.has(key)) {
|
||||
return false;
|
||||
}
|
||||
this.#queue.set(key, config);
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* Atomically snapshots and clears the queue.
|
||||
* @returns All queued entries at the time of the call.
|
||||
*/
|
||||
flush(): Array<[string, FontLoadRequestConfig]> {
|
||||
const entries = Array.from(this.#queue.entries());
|
||||
this.#queue.clear();
|
||||
return entries;
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns `true` if the key is currently in the queue.
|
||||
*/
|
||||
has(key: string): boolean {
|
||||
return this.#queue.has(key);
|
||||
}
|
||||
|
||||
/**
|
||||
* Increments the retry count for a font key.
|
||||
*/
|
||||
incrementRetry(key: string): void {
|
||||
this.#retryCounts.set(key, (this.#retryCounts.get(key) ?? 0) + 1);
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns `true` if the font has reached or exceeded the maximum retry limit.
|
||||
*/
|
||||
isMaxRetriesReached(key: string): boolean {
|
||||
return (this.#retryCounts.get(key) ?? 0) >= this.#MAX_RETRIES;
|
||||
}
|
||||
|
||||
/**
|
||||
* Clears all queued fonts and resets all retry counts.
|
||||
*/
|
||||
clear(): void {
|
||||
this.#queue.clear();
|
||||
this.#retryCounts.clear();
|
||||
}
|
||||
}
|
||||
+25
@@ -0,0 +1,25 @@
|
||||
import { generateFontKey } from './generateFontKey';
|
||||
|
||||
describe('generateFontKey', () => {
|
||||
it('should throw an error if font id is not provided', () => {
|
||||
const config = { weight: 400, isVariable: false };
|
||||
// @ts-expect-error
|
||||
expect(() => generateFontKey(config)).toThrow('Font id is required');
|
||||
});
|
||||
|
||||
it('should generate a font key for a variable font', () => {
|
||||
const config = { id: 'Roboto', weight: 400, isVariable: true };
|
||||
expect(generateFontKey(config)).toBe('roboto@vf');
|
||||
});
|
||||
|
||||
it('should throw an error if font weight is not provided and is not a variable font', () => {
|
||||
const config = { id: 'Roboto', isVariable: false };
|
||||
// @ts-expect-error
|
||||
expect(() => generateFontKey(config)).toThrow('Font weight is required');
|
||||
});
|
||||
|
||||
it('should generate a font key for a non-variable font', () => {
|
||||
const config = { id: 'Roboto', weight: 400, isVariable: false };
|
||||
expect(generateFontKey(config)).toBe('roboto@400');
|
||||
});
|
||||
});
|
||||
+22
@@ -0,0 +1,22 @@
|
||||
import type { FontLoadRequestConfig } from '../../../../types';
|
||||
|
||||
export type PartialConfig = Pick<FontLoadRequestConfig, 'id' | 'weight' | 'isVariable'>;
|
||||
|
||||
/**
|
||||
* Generates a font key for a given font load request configuration.
|
||||
* @param config - The font load request configuration.
|
||||
* @returns The generated font key.
|
||||
*/
|
||||
export function generateFontKey(config: PartialConfig): string {
|
||||
if (!config.id) {
|
||||
throw new Error('Font id is required');
|
||||
}
|
||||
if (config.isVariable) {
|
||||
return `${config.id.toLowerCase()}@vf`;
|
||||
}
|
||||
|
||||
if (!config.weight) {
|
||||
throw new Error('Font weight is required');
|
||||
}
|
||||
return `${config.id.toLowerCase()}@${config.weight}`;
|
||||
}
|
||||
+41
@@ -0,0 +1,41 @@
|
||||
import {
|
||||
beforeEach,
|
||||
describe,
|
||||
expect,
|
||||
it,
|
||||
} from 'vitest';
|
||||
import {
|
||||
Concurrency,
|
||||
getEffectiveConcurrency,
|
||||
} from './getEffectiveConcurrency';
|
||||
|
||||
describe('getEffectiveConcurrency', () => {
|
||||
beforeEach(() => {
|
||||
const nav = navigator as any;
|
||||
nav.connection = null;
|
||||
});
|
||||
|
||||
it('should return MAX when connection is not available', () => {
|
||||
const nav = navigator as any;
|
||||
nav.connection = null;
|
||||
expect(getEffectiveConcurrency()).toBe(Concurrency.MAX);
|
||||
});
|
||||
|
||||
it('should return MIN for slow-2g or 2g connection', () => {
|
||||
const nav = navigator as any;
|
||||
nav.connection = { effectiveType: 'slow-2g' };
|
||||
expect(getEffectiveConcurrency()).toBe(Concurrency.MIN);
|
||||
});
|
||||
|
||||
it('should return AVERAGE for 3g connection', () => {
|
||||
const nav = navigator as any;
|
||||
nav.connection = { effectiveType: '3g' };
|
||||
expect(getEffectiveConcurrency()).toBe(Concurrency.AVERAGE);
|
||||
});
|
||||
|
||||
it('should return MAX for other connection types', () => {
|
||||
const nav = navigator as any;
|
||||
nav.connection = { effectiveType: '4g' };
|
||||
expect(getEffectiveConcurrency()).toBe(Concurrency.MAX);
|
||||
});
|
||||
});
|
||||
+26
@@ -0,0 +1,26 @@
|
||||
export enum Concurrency {
|
||||
MIN = 1,
|
||||
AVERAGE = 2,
|
||||
MAX = 4,
|
||||
}
|
||||
|
||||
/**
|
||||
* Calculates the amount of fonts for concurrent download based on the user internet connection
|
||||
*/
|
||||
export function getEffectiveConcurrency(): number {
|
||||
const nav = navigator as any;
|
||||
const connection = nav.connection;
|
||||
if (!connection) {
|
||||
return Concurrency.MAX;
|
||||
}
|
||||
|
||||
switch (connection.effectiveType) {
|
||||
case 'slow-2g':
|
||||
case '2g':
|
||||
return Concurrency.MIN;
|
||||
case '3g':
|
||||
return Concurrency.AVERAGE;
|
||||
default:
|
||||
return Concurrency.MAX;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,4 @@
|
||||
export { generateFontKey } from './generateFontKey/generateFontKey';
|
||||
export { getEffectiveConcurrency } from './getEffectiveConcurrency/getEffectiveConcurrency';
|
||||
export { loadFont } from './loadFont/loadFont';
|
||||
export { yieldToMainThread } from './yieldToMainThread/yieldToMainThread';
|
||||
@@ -0,0 +1,95 @@
|
||||
/**
|
||||
* @vitest-environment jsdom
|
||||
*/
|
||||
import { FontParseError } from '../../errors';
|
||||
import { loadFont } from './loadFont';
|
||||
|
||||
describe('loadFont', () => {
|
||||
let mockFontInstance: any;
|
||||
let mockFontFaceSet: { add: ReturnType<typeof vi.fn>; delete: ReturnType<typeof vi.fn> };
|
||||
|
||||
beforeEach(() => {
|
||||
mockFontFaceSet = { add: vi.fn(), delete: vi.fn() };
|
||||
Object.defineProperty(document, 'fonts', { value: mockFontFaceSet, configurable: true, writable: true });
|
||||
|
||||
const MockFontFace = vi.fn(
|
||||
function(this: any, name: string, buffer: BufferSource, options: FontFaceDescriptors) {
|
||||
this.name = name;
|
||||
this.buffer = buffer;
|
||||
this.options = options;
|
||||
this.load = vi.fn().mockResolvedValue(this);
|
||||
mockFontInstance = this;
|
||||
},
|
||||
);
|
||||
vi.stubGlobal('FontFace', MockFontFace);
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
vi.unstubAllGlobals();
|
||||
});
|
||||
|
||||
it('constructs FontFace with exact weight for static fonts', async () => {
|
||||
const buffer = new ArrayBuffer(8);
|
||||
await loadFont({ name: 'Roboto', weight: 400 }, buffer);
|
||||
|
||||
expect(FontFace).toHaveBeenCalledWith('Roboto', buffer, expect.objectContaining({ weight: '400' }));
|
||||
});
|
||||
|
||||
it('constructs FontFace with weight range for variable fonts', async () => {
|
||||
const buffer = new ArrayBuffer(8);
|
||||
await loadFont({ name: 'Roboto', weight: 400, isVariable: true }, buffer);
|
||||
|
||||
expect(FontFace).toHaveBeenCalledWith('Roboto', buffer, expect.objectContaining({ weight: '100 900' }));
|
||||
});
|
||||
|
||||
it('sets style: normal and display: swap on FontFace options', async () => {
|
||||
await loadFont({ name: 'Lato', weight: 700 }, new ArrayBuffer(8));
|
||||
|
||||
expect(FontFace).toHaveBeenCalledWith(
|
||||
'Lato',
|
||||
expect.anything(),
|
||||
expect.objectContaining({ style: 'normal', display: 'swap' }),
|
||||
);
|
||||
});
|
||||
|
||||
it('passes the buffer as the second argument to FontFace', async () => {
|
||||
const buffer = new ArrayBuffer(16);
|
||||
await loadFont({ name: 'Inter', weight: 400 }, buffer);
|
||||
|
||||
expect(FontFace).toHaveBeenCalledWith('Inter', buffer, expect.anything());
|
||||
});
|
||||
|
||||
it('calls font.load() and adds the font to document.fonts', async () => {
|
||||
const buffer = new ArrayBuffer(8);
|
||||
const result = await loadFont({ name: 'Inter', weight: 400 }, buffer);
|
||||
|
||||
expect(mockFontInstance.load).toHaveBeenCalledOnce();
|
||||
expect(mockFontFaceSet.add).toHaveBeenCalledWith(mockFontInstance);
|
||||
expect(result).toBe(mockFontInstance);
|
||||
});
|
||||
|
||||
it('throws FontParseError when font.load() rejects', async () => {
|
||||
const loadError = new Error('parse failed');
|
||||
const MockFontFace = vi.fn(
|
||||
function(this: any, name: string, buffer: BufferSource, options: FontFaceDescriptors) {
|
||||
this.load = vi.fn().mockRejectedValue(loadError);
|
||||
},
|
||||
);
|
||||
vi.stubGlobal('FontFace', MockFontFace);
|
||||
|
||||
await expect(loadFont({ name: 'Broken', weight: 400 }, new ArrayBuffer(8))).rejects.toBeInstanceOf(
|
||||
FontParseError,
|
||||
);
|
||||
});
|
||||
|
||||
it('throws FontParseError when document.fonts.add throws', async () => {
|
||||
const addError = new Error('add failed');
|
||||
mockFontFaceSet.add.mockImplementation(() => {
|
||||
throw addError;
|
||||
});
|
||||
|
||||
await expect(loadFont({ name: 'Broken', weight: 400 }, new ArrayBuffer(8))).rejects.toBeInstanceOf(
|
||||
FontParseError,
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,27 @@
|
||||
import type { FontLoadRequestConfig } from '../../../../types';
|
||||
import { FontParseError } from '../../errors';
|
||||
|
||||
export type PartialConfig = Pick<FontLoadRequestConfig, 'weight' | 'name' | 'isVariable'>;
|
||||
/**
|
||||
* Loads a font from a buffer and adds it to the document's font collection.
|
||||
* @param config - The font load request configuration.
|
||||
* @param buffer - The buffer containing the font data.
|
||||
* @returns A promise that resolves to the loaded `FontFace`.
|
||||
* @throws {@link FontParseError} When the font buffer cannot be parsed or added to the document font set.
|
||||
*/
|
||||
export async function loadFont(config: PartialConfig, buffer: BufferSource): Promise<FontFace> {
|
||||
try {
|
||||
const weightRange = config.isVariable ? '100 900' : `${config.weight}`;
|
||||
const font = new FontFace(config.name, buffer, {
|
||||
weight: weightRange,
|
||||
style: 'normal',
|
||||
display: 'swap',
|
||||
});
|
||||
await font.load();
|
||||
document.fonts.add(font);
|
||||
|
||||
return font;
|
||||
} catch (error) {
|
||||
throw new FontParseError(config.name, error);
|
||||
}
|
||||
}
|
||||
+17
@@ -0,0 +1,17 @@
|
||||
import { yieldToMainThread } from './yieldToMainThread';
|
||||
|
||||
describe('yieldToMainThread', () => {
|
||||
it('uses scheduler.yield when available', async () => {
|
||||
const mockYield = vi.fn().mockResolvedValue(undefined);
|
||||
vi.stubGlobal('scheduler', { yield: mockYield });
|
||||
|
||||
await yieldToMainThread();
|
||||
|
||||
expect(mockYield).toHaveBeenCalledOnce();
|
||||
vi.unstubAllGlobals();
|
||||
});
|
||||
it('falls back to MessageChannel when scheduler is unavailable', async () => {
|
||||
// scheduler is not defined in jsdom by default
|
||||
await expect(yieldToMainThread()).resolves.toBeUndefined();
|
||||
});
|
||||
});
|
||||
+14
@@ -0,0 +1,14 @@
|
||||
/**
|
||||
* Yields to main thread during CPU-intensive parsing. Uses scheduler.yield() where available or MessageChannel fallback.
|
||||
*/
|
||||
export async function yieldToMainThread(): Promise<void> {
|
||||
if (typeof scheduler !== 'undefined' && 'yield' in scheduler) {
|
||||
await scheduler.yield();
|
||||
} else {
|
||||
await new Promise<void>(resolve => {
|
||||
const ch = new MessageChannel();
|
||||
ch.port1.onmessage = () => resolve();
|
||||
ch.port2.postMessage(null);
|
||||
});
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user