tiny-essentials 1.29.0 → 1.29.2

package/dist/v1/basics/media/youtube.cjs

@@ -0,0 +1,275 @@
+'use strict';
+
+/**
+ * @typedef {'default' | 'mqdefault' | 'hqdefault' | 'sddefault' | 'maxresdefault'} YouTubeThumbnailQuality
+ */
+
+/**
+ * @typedef {Object} YouTubeOEmbedResponse
+ * @property {string} title - Video title.
+ * @property {string} author_name - Channel display name.
+ * @property {string} author_url - Channel URL.
+ * @property {string} type - Resource type returned by the provider (e.g. "video").
+ * @property {string} version - oEmbed version.
+ * @property {string} provider_name - Always "YouTube".
+ * @property {string} provider_url - Provider root URL.
+ * @property {string} html - Ready to use iframe markup.
+ * @property {number} width - Suggested iframe width in pixels.
+ * @property {number} height - Suggested iframe height in pixels.
+ * @property {string} thumbnail_url - Thumbnail URL provided by the provider.
+ * @property {number} thumbnail_width - Thumbnail width in pixels.
+ * @property {number} thumbnail_height - Thumbnail height in pixels.
+ */
+
+/**
+ * @typedef {Object} FetchYouTubeOEmbedOptions
+ * @property {AbortSignal} [signal] - Optional abort signal forwarded to fetch.
+ * @property {typeof fetch} [fetchImpl] - Injectable fetch implementation (useful for tests).
+ */
+
+const YOUTUBE_VIDEO_ID_PATTERN = /^[A-Za-z0-9_-]{11}$/;
+const YOUTUBE_OEMBED_ENDPOINT = 'https://www.youtube.com/oembed';
+const YOUTUBE_THUMBNAIL_ENDPOINT = 'https://i.ytimg.com/vi';
+const YOUTUBE_ALLOWED_HOSTS = new Set([
+  'youtube.com',
+  'm.youtube.com',
+  'music.youtube.com',
+  'youtube-nocookie.com',
+  'youtu.be',
+]);
+const YOUTUBE_ALLOWED_PROTOCOLS = new Set(['http:', 'https:']);
+const YOUTUBE_THUMBNAIL_QUALITIES = new Set([
+  'default',
+  'mqdefault',
+  'hqdefault',
+  'sddefault',
+  'maxresdefault',
+]);
+
+const YOUTUBE_OEMBED_TYPE = 'video';
+
+/**
+ * @param {unknown} value - Value to inspect.
+ * @param {string} label - Human readable path used in the error message.
+ * @returns {Record<string, unknown>} The same value, narrowed to a plain object.
+ * @throws {TypeError} If `value` is not a non-null, non-array object.
+ */
+function assertPlainObject(value, label) {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new TypeError(
+      `${label} must be a plain object, received ${Array.isArray(value) ? 'array' : typeof value}.`,
+    );
+  }
+
+  return /** @type {Record<string, unknown>} */ (value);
+}
+
+/**
+ * @param {Record<string, unknown>} payload - Object being read.
+ * @param {string} key - Property name.
+ * @param {string} context - Caller name used in the error message.
+ * @returns {string} The validated, trimmed string.
+ * @throws {TypeError} If the property is not a string.
+ * @throws {RangeError} If the property is an empty string.
+ */
+function readRequiredString(payload, key, context) {
+  const value = payload[key];
+
+  if (typeof value !== 'string') {
+    throw new TypeError(`${context}: "${key}" must be a string, received ${typeof value}.`);
+  }
+
+  const trimmed = value.trim();
+
+  if (trimmed.length === 0) {
+    throw new RangeError(`${context}: "${key}" cannot be empty.`);
+  }
+
+  return trimmed;
+}
+
+/**
+ * @param {Record<string, unknown>} payload - Object being read.
+ * @param {string} key - Property name.
+ * @param {string} context - Caller name used in the error message.
+ * @returns {number} The validated integer.
+ * @throws {TypeError} If the property is not a number.
+ * @throws {RangeError} If the property is not a positive integer.
+ */
+function readRequiredPositiveInteger(payload, key, context) {
+  const value = payload[key];
+
+  if (typeof value !== 'number') {
+    throw new TypeError(`${context}: "${key}" must be a number, received ${typeof value}.`);
+  }
+
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new RangeError(`${context}: "${key}" must be a positive integer, received ${value}.`);
+  }
+
+  return value;
+}
+
+/**
+ * Deeply validates a YouTube oEmbed payload.
+ * @param {unknown} payload - Raw value returned by `response.json()`.
+ * @param {string} [context='assertYouTubeOEmbedResponse'] - Caller name used in error messages.
+ * @returns {YouTubeOEmbedResponse} A brand new, fully validated object.
+ * @throws {TypeError} If the payload or any of its properties has the wrong type.
+ * @throws {RangeError} If a numeric property is not a positive integer.
+ */
+function assertYouTubeOEmbedResponse(payload, context = 'assertYouTubeOEmbedResponse') {
+  const source = assertPlainObject(payload, `${context}: payload`);
+  const type = readRequiredString(source, 'type', context);
+
+  if (type !== YOUTUBE_OEMBED_TYPE) {
+    throw new RangeError(
+      `${context}: "type" must be "${YOUTUBE_OEMBED_TYPE}", received "${type}".`,
+    );
+  }
+
+  return {
+    title: readRequiredString(source, 'title', context),
+    author_name: readRequiredString(source, 'author_name', context),
+    author_url: readRequiredString(source, 'author_url', context),
+    type,
+    version: readRequiredString(source, 'version', context),
+    provider_name: readRequiredString(source, 'provider_name', context),
+    provider_url: readRequiredString(source, 'provider_url', context),
+    html: readRequiredString(source, 'html', context),
+    width: readRequiredPositiveInteger(source, 'width', context),
+    height: readRequiredPositiveInteger(source, 'height', context),
+    thumbnail_url: readRequiredString(source, 'thumbnail_url', context),
+    thumbnail_width: readRequiredPositiveInteger(source, 'thumbnail_width', context),
+    thumbnail_height: readRequiredPositiveInteger(source, 'thumbnail_height', context),
+  };
+}
+
+/**
+ * Extracts a YouTube video id from a raw id or a full YouTube URL.
+ * @param {string} input - Raw 11 character video id or a full YouTube URL.
+ * @returns {string} The 11 character video id.
+ * @throws {TypeError} If `input` is not a string.
+ * @throws {RangeError} If `input` is empty or the host is not a YouTube host.
+ * @throws {SyntaxError} If `input` is not a valid id nor a parseable URL containing an id.
+ */
+function extractYouTubeVideoId(input) {
+  if (typeof input !== 'string') {
+    throw new TypeError('extractYouTubeVideoId: "input" must be a string.');
+  }
+
+  const trimmedInput = input.trim();
+
+  if (trimmedInput.length === 0) {
+    throw new RangeError('extractYouTubeVideoId: "input" cannot be empty.');
+  }
+
+  if (YOUTUBE_VIDEO_ID_PATTERN.test(trimmedInput)) {
+    return trimmedInput;
+  }
+
+  let parsedUrl;
+
+  try {
+    parsedUrl = new URL(trimmedInput);
+  } catch {
+    throw new SyntaxError(
+      `extractYouTubeVideoId: "${input}" is neither a video id nor a valid URL.`,
+    );
+  }
+
+  if (!YOUTUBE_ALLOWED_PROTOCOLS.has(parsedUrl.protocol)) {
+    throw new RangeError(`extractYouTubeVideoId: unsupported protocol "${parsedUrl.protocol}".`);
+  }
+
+  const host = parsedUrl.hostname.replace(/^www\./, '').toLowerCase();
+
+  if (!YOUTUBE_ALLOWED_HOSTS.has(host)) {
+    throw new RangeError(`extractYouTubeVideoId: unsupported host "${host}".`);
+  }
+
+  const pathMatch = parsedUrl.pathname.match(/^\/(?:embed|shorts|live|v)\/([A-Za-z0-9_-]{11})/);
+  const videoId =
+    host === 'youtu.be'
+      ? parsedUrl.pathname.slice(1).split('/')[0]
+      : (parsedUrl.searchParams.get('v') ?? pathMatch?.[1] ?? null);
+
+  if (typeof videoId !== 'string' || !YOUTUBE_VIDEO_ID_PATTERN.test(videoId)) {
+    throw new SyntaxError(`extractYouTubeVideoId: no valid video id found in "${input}".`);
+  }
+
+  return videoId;
+}
+
+/**
+ * Fetches the oEmbed metadata of a YouTube video.
+ * @param {string} videoIdOrUrl - Raw 11 character video id or a full YouTube URL.
+ * @param {FetchYouTubeOEmbedOptions} [options] - Optional fetch configuration.
+ * @returns {Promise<YouTubeOEmbedResponse>} The fully validated oEmbed payload.
+ * @throws {TypeError} If `options` is not a plain object, if `options.signal` is not an `AbortSignal`,
+ * if `options.fetchImpl` is not a function, or if the payload has a wrong type.
+ * @throws {RangeError} If the payload contains an out of range numeric value.
+ * @throws {Error} If the HTTP request fails or returns a non 2xx status.
+ */
+async function fetchYouTubeOEmbed(videoIdOrUrl, options = {}) {
+  const context = 'fetchYouTubeOEmbed';
+  const settings = assertPlainObject(options, `${context}: "options"`);
+  const { signal, fetchImpl = fetch } = settings;
+
+  if (signal !== undefined && !(signal instanceof AbortSignal)) {
+    throw new TypeError(`${context}: "options.signal" must be an AbortSignal.`);
+  }
+
+  if (typeof fetchImpl !== 'function') {
+    throw new TypeError(`${context}: "options.fetchImpl" must be a function.`);
+  }
+
+  const videoId = extractYouTubeVideoId(videoIdOrUrl);
+  const endpoint = new URL(YOUTUBE_OEMBED_ENDPOINT);
+
+  endpoint.searchParams.set('format', 'json');
+  endpoint.searchParams.set('url', `https://www.youtube.com/watch?v=${videoId}`);
+
+  const response = await fetchImpl(endpoint, { method: 'GET', signal });
+
+  if (typeof response !== 'object' || response === null || typeof response.json !== 'function') {
+    throw new TypeError(`${context}: "options.fetchImpl" did not resolve to a Response.`);
+  }
+
+  if (!response.ok) {
+    throw new Error(
+      `${context}: request failed with status ${response.status} for video "${videoId}".`,
+    );
+  }
+
+  return assertYouTubeOEmbedResponse(await response.json(), context);
+}
+
+/**
+ * Builds the thumbnail URL of a YouTube video without any network request.
+ * @param {string} videoIdOrUrl - Raw 11 character video id or a full YouTube URL.
+ * @param {YouTubeThumbnailQuality} [quality='hqdefault'] - Thumbnail resolution.
+ * @returns {string} The thumbnail URL.
+ * @throws {TypeError} If `quality` is not a string.
+ * @throws {RangeError} If `quality` is not a supported thumbnail quality.
+ */
+function getYouTubeThumbnailUrl(videoIdOrUrl, quality = 'hqdefault') {
+  if (typeof quality !== 'string') {
+    throw new TypeError(
+      `getYouTubeThumbnailUrl: "quality" must be a string, received ${typeof quality}.`,
+    );
+  }
+
+  if (!YOUTUBE_THUMBNAIL_QUALITIES.has(quality)) {
+    throw new RangeError(
+      `getYouTubeThumbnailUrl: "quality" must be one of ${[...YOUTUBE_THUMBNAIL_QUALITIES].join(', ')}.`,
+    );
+  }
+
+  return `${YOUTUBE_THUMBNAIL_ENDPOINT}/${extractYouTubeVideoId(videoIdOrUrl)}/${quality}.jpg`;
+}
+
+exports.assertYouTubeOEmbedResponse = assertYouTubeOEmbedResponse;
+exports.extractYouTubeVideoId = extractYouTubeVideoId;
+exports.fetchYouTubeOEmbed = fetchYouTubeOEmbed;
+exports.getYouTubeThumbnailUrl = getYouTubeThumbnailUrl;

package/dist/v1/basics/media/youtube.d.mts

@@ -0,0 +1,107 @@
+/**
+ * @typedef {'default' | 'mqdefault' | 'hqdefault' | 'sddefault' | 'maxresdefault'} YouTubeThumbnailQuality
+ */
+export type YouTubeThumbnailQuality = 'default' | 'mqdefault' | 'hqdefault' | 'sddefault' | 'maxresdefault';
+export type YouTubeOEmbedResponse = {
+    /**
+     * - Video title.
+     */
+    title: string;
+    /**
+     * - Channel display name.
+     */
+    author_name: string;
+    /**
+     * - Channel URL.
+     */
+    author_url: string;
+    /**
+     * - Resource type returned by the provider (e.g. "video").
+     */
+    type: string;
+    /**
+     * - oEmbed version.
+     */
+    version: string;
+    /**
+     * - Always "YouTube".
+     */
+    provider_name: string;
+    /**
+     * - Provider root URL.
+     */
+    provider_url: string;
+    /**
+     * - Ready to use iframe markup.
+     */
+    html: string;
+    /**
+     * - Suggested iframe width in pixels.
+     */
+    width: number;
+    /**
+     * - Suggested iframe height in pixels.
+     */
+    height: number;
+    /**
+     * - Thumbnail URL provided by the provider.
+     */
+    thumbnail_url: string;
+    /**
+     * - Thumbnail width in pixels.
+     */
+    thumbnail_width: number;
+    /**
+     * - Thumbnail height in pixels.
+     */
+    thumbnail_height: number;
+};
+export type FetchYouTubeOEmbedOptions = {
+    /**
+     * - Optional abort signal forwarded to fetch.
+     */
+    signal?: AbortSignal;
+    /**
+     * - Injectable fetch implementation (useful for tests).
+     */
+    fetchImpl?: typeof fetch;
+};
+/**
+ * Deeply validates a YouTube oEmbed payload.
+ * @param {unknown} payload - Raw value returned by `response.json()`.
+ * @param {string} [context='assertYouTubeOEmbedResponse'] - Caller name used in error messages.
+ * @returns {YouTubeOEmbedResponse} A brand new, fully validated object.
+ * @throws {TypeError} If the payload or any of its properties has the wrong type.
+ * @throws {RangeError} If a numeric property is not a positive integer.
+ */
+export declare function assertYouTubeOEmbedResponse(payload: unknown, context?: string): YouTubeOEmbedResponse;
+/**
+ * Extracts a YouTube video id from a raw id or a full YouTube URL.
+ * @param {string} input - Raw 11 character video id or a full YouTube URL.
+ * @returns {string} The 11 character video id.
+ * @throws {TypeError} If `input` is not a string.
+ * @throws {RangeError} If `input` is empty or the host is not a YouTube host.
+ * @throws {SyntaxError} If `input` is not a valid id nor a parseable URL containing an id.
+ */
+export declare function extractYouTubeVideoId(input: string): string;
+/**
+ * Fetches the oEmbed metadata of a YouTube video.
+ * @param {string} videoIdOrUrl - Raw 11 character video id or a full YouTube URL.
+ * @param {FetchYouTubeOEmbedOptions} [options] - Optional fetch configuration.
+ * @returns {Promise<YouTubeOEmbedResponse>} The fully validated oEmbed payload.
+ * @throws {TypeError} If `options` is not a plain object, if `options.signal` is not an `AbortSignal`,
+ * if `options.fetchImpl` is not a function, or if the payload has a wrong type.
+ * @throws {RangeError} If the payload contains an out of range numeric value.
+ * @throws {Error} If the HTTP request fails or returns a non 2xx status.
+ */
+export declare function fetchYouTubeOEmbed(videoIdOrUrl: string, options?: FetchYouTubeOEmbedOptions): Promise<YouTubeOEmbedResponse>;
+/**
+ * Builds the thumbnail URL of a YouTube video without any network request.
+ * @param {string} videoIdOrUrl - Raw 11 character video id or a full YouTube URL.
+ * @param {YouTubeThumbnailQuality} [quality='hqdefault'] - Thumbnail resolution.
+ * @returns {string} The thumbnail URL.
+ * @throws {TypeError} If `quality` is not a string.
+ * @throws {RangeError} If `quality` is not a supported thumbnail quality.
+ */
+export declare function getYouTubeThumbnailUrl(videoIdOrUrl: string, quality?: YouTubeThumbnailQuality): string;
+//# sourceMappingURL=youtube.d.mts.map

package/dist/v1/basics/media/youtube.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"youtube.d.mts","sourceRoot":"","sources":["../../../../src/v1/basics/media/youtube.mjs"],"names":[],"mappings":"AAAA;;GAEG;AADA,YAAiF,uBAAuB,GAA9F,SAAS,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,eAAe,CAAyB;AAIxG,YAAkB,qBAAqB,GACvC;;;;IAAmB,KAAK,EAAb,MAAM,CACjB;;;;IAAmB,WAAW,EAAnB,MAAM,CACjB;;;;IAAmB,UAAU,EAAlB,MAAM,CACjB;;;;IAAmB,IAAI,EAAZ,MAAM,CACjB;;;;IAAmB,OAAO,EAAf,MAAM,CACjB;;;;IAAmB,aAAa,EAArB,MAAM,CACjB;;;;IAAmB,YAAY,EAApB,MAAM,CACjB;;;;IAAmB,IAAI,EAAZ,MAAM,CACjB;;;;IAAmB,KAAK,EAAb,MAAM,CACjB;;;;IAAmB,MAAM,EAAd,MAAM,CACjB;;;;IAAmB,aAAa,EAArB,MAAM,CACjB;;;;IAAmB,eAAe,EAAvB,MAAM,CACjB;;;;IAAmB,gBAAgB,EAAxB,MAAM,CACnB;CAAA,CAAA;AAGE,YAAkB,yBAAyB,GAC3C;;;;IAAyB,MAAM,AAA/B,CACA,EADW,WAAW,CACtB;;;;IAA0B,SAAS,AAAnC,CACF,EADa,OAAO,KAAK,CACzB;CAAA,CAAA;AAqFD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EANxC,OAMwC,EAAE,OAAO,AALzD,CACA,EADQ,MAKiF,GAJ/E,qBAAqB,CA6BjC;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EANhC,MAMgC,GAL9B,MAAM,CAmDlB;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CAAC,YAAY,EAR1C,MAQ0C,EAAE,OAAO,AAP3D,CACA,EADQ,yBAOwD,GANtD,OAAO,CAAC,qBAAqB,CAAC,CAsC1C;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,YAAY,EANxC,MAMwC,EAAE,OAAO,AALzD,CACA,EADQ,uBAK+D,GAJ7D,MAAM,CAkBlB"}

package/dist/v1/basics/media/youtube.mjs

@@ -0,0 +1,214 @@
+/**
+ * @typedef {'default' | 'mqdefault' | 'hqdefault' | 'sddefault' | 'maxresdefault'} YouTubeThumbnailQuality
+ */
+/**
+ * @typedef {Object} YouTubeOEmbedResponse
+ * @property {string} title - Video title.
+ * @property {string} author_name - Channel display name.
+ * @property {string} author_url - Channel URL.
+ * @property {string} type - Resource type returned by the provider (e.g. "video").
+ * @property {string} version - oEmbed version.
+ * @property {string} provider_name - Always "YouTube".
+ * @property {string} provider_url - Provider root URL.
+ * @property {string} html - Ready to use iframe markup.
+ * @property {number} width - Suggested iframe width in pixels.
+ * @property {number} height - Suggested iframe height in pixels.
+ * @property {string} thumbnail_url - Thumbnail URL provided by the provider.
+ * @property {number} thumbnail_width - Thumbnail width in pixels.
+ * @property {number} thumbnail_height - Thumbnail height in pixels.
+ */
+/**
+ * @typedef {Object} FetchYouTubeOEmbedOptions
+ * @property {AbortSignal} [signal] - Optional abort signal forwarded to fetch.
+ * @property {typeof fetch} [fetchImpl] - Injectable fetch implementation (useful for tests).
+ */
+const YOUTUBE_VIDEO_ID_PATTERN = /^[A-Za-z0-9_-]{11}$/;
+const YOUTUBE_OEMBED_ENDPOINT = 'https://www.youtube.com/oembed';
+const YOUTUBE_THUMBNAIL_ENDPOINT = 'https://i.ytimg.com/vi';
+const YOUTUBE_ALLOWED_HOSTS = new Set([
+    'youtube.com',
+    'm.youtube.com',
+    'music.youtube.com',
+    'youtube-nocookie.com',
+    'youtu.be',
+]);
+const YOUTUBE_ALLOWED_PROTOCOLS = new Set(['http:', 'https:']);
+const YOUTUBE_THUMBNAIL_QUALITIES = new Set([
+    'default',
+    'mqdefault',
+    'hqdefault',
+    'sddefault',
+    'maxresdefault',
+]);
+const YOUTUBE_OEMBED_TYPE = 'video';
+/**
+ * @param {unknown} value - Value to inspect.
+ * @param {string} label - Human readable path used in the error message.
+ * @returns {Record<string, unknown>} The same value, narrowed to a plain object.
+ * @throws {TypeError} If `value` is not a non-null, non-array object.
+ */
+function assertPlainObject(value, label) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new TypeError(`${label} must be a plain object, received ${Array.isArray(value) ? 'array' : typeof value}.`);
+    }
+    return /** @type {Record<string, unknown>} */ (value);
+}
+/**
+ * @param {Record<string, unknown>} payload - Object being read.
+ * @param {string} key - Property name.
+ * @param {string} context - Caller name used in the error message.
+ * @returns {string} The validated, trimmed string.
+ * @throws {TypeError} If the property is not a string.
+ * @throws {RangeError} If the property is an empty string.
+ */
+function readRequiredString(payload, key, context) {
+    const value = payload[key];
+    if (typeof value !== 'string') {
+        throw new TypeError(`${context}: "${key}" must be a string, received ${typeof value}.`);
+    }
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        throw new RangeError(`${context}: "${key}" cannot be empty.`);
+    }
+    return trimmed;
+}
+/**
+ * @param {Record<string, unknown>} payload - Object being read.
+ * @param {string} key - Property name.
+ * @param {string} context - Caller name used in the error message.
+ * @returns {number} The validated integer.
+ * @throws {TypeError} If the property is not a number.
+ * @throws {RangeError} If the property is not a positive integer.
+ */
+function readRequiredPositiveInteger(payload, key, context) {
+    const value = payload[key];
+    if (typeof value !== 'number') {
+        throw new TypeError(`${context}: "${key}" must be a number, received ${typeof value}.`);
+    }
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new RangeError(`${context}: "${key}" must be a positive integer, received ${value}.`);
+    }
+    return value;
+}
+/**
+ * Deeply validates a YouTube oEmbed payload.
+ * @param {unknown} payload - Raw value returned by `response.json()`.
+ * @param {string} [context='assertYouTubeOEmbedResponse'] - Caller name used in error messages.
+ * @returns {YouTubeOEmbedResponse} A brand new, fully validated object.
+ * @throws {TypeError} If the payload or any of its properties has the wrong type.
+ * @throws {RangeError} If a numeric property is not a positive integer.
+ */
+export function assertYouTubeOEmbedResponse(payload, context = 'assertYouTubeOEmbedResponse') {
+    const source = assertPlainObject(payload, `${context}: payload`);
+    const type = readRequiredString(source, 'type', context);
+    if (type !== YOUTUBE_OEMBED_TYPE) {
+        throw new RangeError(`${context}: "type" must be "${YOUTUBE_OEMBED_TYPE}", received "${type}".`);
+    }
+    return {
+        title: readRequiredString(source, 'title', context),
+        author_name: readRequiredString(source, 'author_name', context),
+        author_url: readRequiredString(source, 'author_url', context),
+        type,
+        version: readRequiredString(source, 'version', context),
+        provider_name: readRequiredString(source, 'provider_name', context),
+        provider_url: readRequiredString(source, 'provider_url', context),
+        html: readRequiredString(source, 'html', context),
+        width: readRequiredPositiveInteger(source, 'width', context),
+        height: readRequiredPositiveInteger(source, 'height', context),
+        thumbnail_url: readRequiredString(source, 'thumbnail_url', context),
+        thumbnail_width: readRequiredPositiveInteger(source, 'thumbnail_width', context),
+        thumbnail_height: readRequiredPositiveInteger(source, 'thumbnail_height', context),
+    };
+}
+/**
+ * Extracts a YouTube video id from a raw id or a full YouTube URL.
+ * @param {string} input - Raw 11 character video id or a full YouTube URL.
+ * @returns {string} The 11 character video id.
+ * @throws {TypeError} If `input` is not a string.
+ * @throws {RangeError} If `input` is empty or the host is not a YouTube host.
+ * @throws {SyntaxError} If `input` is not a valid id nor a parseable URL containing an id.
+ */
+export function extractYouTubeVideoId(input) {
+    if (typeof input !== 'string') {
+        throw new TypeError('extractYouTubeVideoId: "input" must be a string.');
+    }
+    const trimmedInput = input.trim();
+    if (trimmedInput.length === 0) {
+        throw new RangeError('extractYouTubeVideoId: "input" cannot be empty.');
+    }
+    if (YOUTUBE_VIDEO_ID_PATTERN.test(trimmedInput)) {
+        return trimmedInput;
+    }
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(trimmedInput);
+    }
+    catch {
+        throw new SyntaxError(`extractYouTubeVideoId: "${input}" is neither a video id nor a valid URL.`);
+    }
+    if (!YOUTUBE_ALLOWED_PROTOCOLS.has(parsedUrl.protocol)) {
+        throw new RangeError(`extractYouTubeVideoId: unsupported protocol "${parsedUrl.protocol}".`);
+    }
+    const host = parsedUrl.hostname.replace(/^www\./, '').toLowerCase();
+    if (!YOUTUBE_ALLOWED_HOSTS.has(host)) {
+        throw new RangeError(`extractYouTubeVideoId: unsupported host "${host}".`);
+    }
+    const pathMatch = parsedUrl.pathname.match(/^\/(?:embed|shorts|live|v)\/([A-Za-z0-9_-]{11})/);
+    const videoId = host === 'youtu.be'
+        ? parsedUrl.pathname.slice(1).split('/')[0]
+        : (parsedUrl.searchParams.get('v') ?? pathMatch?.[1] ?? null);
+    if (typeof videoId !== 'string' || !YOUTUBE_VIDEO_ID_PATTERN.test(videoId)) {
+        throw new SyntaxError(`extractYouTubeVideoId: no valid video id found in "${input}".`);
+    }
+    return videoId;
+}
+/**
+ * Fetches the oEmbed metadata of a YouTube video.
+ * @param {string} videoIdOrUrl - Raw 11 character video id or a full YouTube URL.
+ * @param {FetchYouTubeOEmbedOptions} [options] - Optional fetch configuration.
+ * @returns {Promise<YouTubeOEmbedResponse>} The fully validated oEmbed payload.
+ * @throws {TypeError} If `options` is not a plain object, if `options.signal` is not an `AbortSignal`,
+ * if `options.fetchImpl` is not a function, or if the payload has a wrong type.
+ * @throws {RangeError} If the payload contains an out of range numeric value.
+ * @throws {Error} If the HTTP request fails or returns a non 2xx status.
+ */
+export async function fetchYouTubeOEmbed(videoIdOrUrl, options = {}) {
+    const context = 'fetchYouTubeOEmbed';
+    const settings = assertPlainObject(options, `${context}: "options"`);
+    const { signal, fetchImpl = fetch } = settings;
+    if (signal !== undefined && !(signal instanceof AbortSignal)) {
+        throw new TypeError(`${context}: "options.signal" must be an AbortSignal.`);
+    }
+    if (typeof fetchImpl !== 'function') {
+        throw new TypeError(`${context}: "options.fetchImpl" must be a function.`);
+    }
+    const videoId = extractYouTubeVideoId(videoIdOrUrl);
+    const endpoint = new URL(YOUTUBE_OEMBED_ENDPOINT);
+    endpoint.searchParams.set('format', 'json');
+    endpoint.searchParams.set('url', `https://www.youtube.com/watch?v=${videoId}`);
+    const response = await fetchImpl(endpoint, { method: 'GET', signal });
+    if (typeof response !== 'object' || response === null || typeof response.json !== 'function') {
+        throw new TypeError(`${context}: "options.fetchImpl" did not resolve to a Response.`);
+    }
+    if (!response.ok) {
+        throw new Error(`${context}: request failed with status ${response.status} for video "${videoId}".`);
+    }
+    return assertYouTubeOEmbedResponse(await response.json(), context);
+}
+/**
+ * Builds the thumbnail URL of a YouTube video without any network request.
+ * @param {string} videoIdOrUrl - Raw 11 character video id or a full YouTube URL.
+ * @param {YouTubeThumbnailQuality} [quality='hqdefault'] - Thumbnail resolution.
+ * @returns {string} The thumbnail URL.
+ * @throws {TypeError} If `quality` is not a string.
+ * @throws {RangeError} If `quality` is not a supported thumbnail quality.
+ */
+export function getYouTubeThumbnailUrl(videoIdOrUrl, quality = 'hqdefault') {
+    if (typeof quality !== 'string') {
+        throw new TypeError(`getYouTubeThumbnailUrl: "quality" must be a string, received ${typeof quality}.`);
+    }
+    if (!YOUTUBE_THUMBNAIL_QUALITIES.has(quality)) {
+        throw new RangeError(`getYouTubeThumbnailUrl: "quality" must be one of ${[...YOUTUBE_THUMBNAIL_QUALITIES].join(', ')}.`);
+    }
+    return `${YOUTUBE_THUMBNAIL_ENDPOINT}/${extractYouTubeVideoId(videoIdOrUrl)}/${quality}.jpg`;
+}

package/dist/v1/index.cjs

@@ -86,6 +86,11 @@ var StorageBucket = require('./libs/fs/plugins/OPFS/StorageBucket.cjs');
 var TinySetMapDatabase = require('./libs/storage/TinySetMapDatabase.cjs');
 var TinyPushManager = require('./libs/sw/browser/TinyPushManager.cjs');
 var TinyNotificationAdapter = require('./libs/sw/browser/TinyNotificationAdapter.cjs');
+var TinyMediaLoader = require('./libs/html/loader/TinyMediaLoader.cjs');
+var TinyImageLoader = require('./libs/html/loader/formats/TinyImageLoader.cjs');
+var TinyFetchLoader = require('./libs/html/loader/formats/TinyFetchLoader.cjs');
+var TinyMediaCache = require('./libs/html/loader/utils/TinyMediaCache.cjs');
+var youtube = require('./basics/media/youtube.cjs');
 
 
 
@@ -307,3 +312,11 @@ exports.TinySetMapDatabase = TinySetMapDatabase.TinySetMapDatabase;
 exports.TinyTableDb = TinySetMapDatabase.TinyTableDb;
 exports.TinyPushManager = TinyPushManager;
 exports.TinyNotificationAdapter = TinyNotificationAdapter;
+exports.TinyMediaLoader = TinyMediaLoader;
+exports.TinyImageLoader = TinyImageLoader;
+exports.TinyFetchLoader = TinyFetchLoader;
+exports.TinyMediaCache = TinyMediaCache;
+exports.assertYouTubeOEmbedResponse = youtube.assertYouTubeOEmbedResponse;
+exports.extractYouTubeVideoId = youtube.extractYouTubeVideoId;
+exports.fetchYouTubeOEmbed = youtube.fetchYouTubeOEmbed;
+exports.getYouTubeThumbnailUrl = youtube.getYouTubeThumbnailUrl;

package/dist/v1/index.d.mts

@@ -84,5 +84,10 @@ import TinyStorageBucketFileSystem from './libs/fs/plugins/OPFS/StorageBucket.mj
 import { TinySetMapDatabase, TinySetDb, TinyMapDb, TinyTableDb } from './libs/storage/TinySetMapDatabase.mjs';
 import TinyPushManager from './libs/sw/browser/TinyPushManager.mjs';
 import { TinyNotificationAdapter } from './build/TinyNotificationAdapter.mjs';
-export { TinyNotificationAdapter, TinyPushManager, TinySetMapDatabase, TinySetDb, TinyMapDb, TinyTableDb, TinyStorageBucketFileSystem, TinyOPFSFileSystem, TinyPluginLayer, TinyPlugin, TinyPluginCore, TinyVersion, TinyThrottledApi, TinyBrowserMonitor, TinyUriParser, TinyHtmlTagRegexBuilder, TinyHttpResponseRegistry, TinyCloner, TinyWebWorker, TinyServiceWorker, TinyMapCache, TinyRouter, TinyDebugger, TinyMediaPlayer, TinyRadioFm, TinyClassManager, FuzzySet, MamdaniInferenceSystem, TinyArrayComparator, TinyTextDiffer, TinyAnalogClock, TinyPkgExportValidator, TinyUploadClicker, TinyColorValidator, TinyLoadingScreen, TinyElementObserver, TinySimpleDice, TinyNeedBar, TinyI18, TinyCookieConsent, TinyInventory, TinyInventoryTrader, TinyArrayPaginator, TinyAdvancedRaffle, TinyDayNightCycle, TinyGamepad, TinyTextarea, TinyNewWinEvents, TinyIframeEvents, TinyLocalStorage, TinyTimeout, TinyColorConverter, TinyClipboard, TinyTextRangeEditor, TinySmartScroller, UltraRandomMsgGen, TinyAfterScrollWatcher, TinyHtml, TinyNotifications, TinyDomReadyManager, TinyDragger, TinyDragDropDetector, TinyToastNotify, TinyNotifyCenter, TinyRateLimiter, ColorSafeStringify, TinyPromiseQueue, TinyLevelUp, createPluginIdChecker, verifyPluginSignature, signPluginIdentity, isClass, isAnyClassInstance, isClassInstance, isValidGlob, compileGlob, compileGlobRegExp, decompileGlob, isBrowser, emailStringRegexBuilder, emailRegex, isValidEmail, findEmailRegex, extractEmails, usernameStringRegexBuilder, usernameRegex, isValidUsername, findUsernameRegex, extractUsernames, urlStringRegexBuilder, urlRegex, isValidUrl, findUrlRegex, extractUrls, ipv6Regex, isValidIPv6, findIPv6Regex, extractIPsV6, ipv4Regex, isValidIPv4, findIPv4Regex, extractIPsV4, getObjTypeRegistry, getObjTypeOrder, segmentExtractorV1, makeSegmentExtractor, jsonFilter, jsonFilterRecursive, jsonFilterByKeys, getUserTimeFormat, getBrowserPings, isBrowserAgent, getBrowserCssPrefix, getDuckTyping, browserIs, isValidObj, createSingletonTask, waitForTrue, multiplyArrayBlocks, createCheckDestroyed, valMediaContentMetadata, valFetchMediaContent, parseMediaMetadata, extractMediaId3Tags, defuzzifyCentroid, trapezoid, diffArrayList, hashText, diffObjList, breakdownDuration, calculateMarketcap, compareMarketcap, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, isDirEmptyAsync, fileSizeAsync, dirSizeAsync, listFilesAsync, listDirsAsync, getLatestBackupPath, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, readJsonFile, writeJsonFile, ensureDirectory, clearDirectoryAsync, clearDirectory, fileExists, dirExists, isDirEmpty, ensureCopyFile, tryDeleteFile, writeTextFile, listFiles, listDirs, fileSize, dirSize, backupFile, restoreLatestBackup, renameFileBatch, renameFileRegex, renameFileAddPrefixSuffix, renameFileNormalizeCase, renameFilePadNumbers, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, checkObj, objTypeName, isObjType, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };
+import TinyMediaLoader from './libs/html/loader/TinyMediaLoader.mjs';
+import TinyImageLoader from './libs/html/loader/formats/TinyImageLoader.mjs';
+import TinyFetchLoader from './libs/html/loader/formats/TinyFetchLoader.mjs';
+import TinyMediaCache from './libs/html/loader/utils/TinyMediaCache.mjs';
+import { getYouTubeThumbnailUrl, fetchYouTubeOEmbed, extractYouTubeVideoId, assertYouTubeOEmbedResponse } from './basics/media/youtube.mjs';
+export { TinyMediaCache, TinyMediaLoader, TinyImageLoader, TinyFetchLoader, TinyNotificationAdapter, TinyPushManager, TinySetMapDatabase, TinySetDb, TinyMapDb, TinyTableDb, TinyStorageBucketFileSystem, TinyOPFSFileSystem, TinyPluginLayer, TinyPlugin, TinyPluginCore, TinyVersion, TinyThrottledApi, TinyBrowserMonitor, TinyUriParser, TinyHtmlTagRegexBuilder, TinyHttpResponseRegistry, TinyCloner, TinyWebWorker, TinyServiceWorker, TinyMapCache, TinyRouter, TinyDebugger, TinyMediaPlayer, TinyRadioFm, TinyClassManager, FuzzySet, MamdaniInferenceSystem, TinyArrayComparator, TinyTextDiffer, TinyAnalogClock, TinyPkgExportValidator, TinyUploadClicker, TinyColorValidator, TinyLoadingScreen, TinyElementObserver, TinySimpleDice, TinyNeedBar, TinyI18, TinyCookieConsent, TinyInventory, TinyInventoryTrader, TinyArrayPaginator, TinyAdvancedRaffle, TinyDayNightCycle, TinyGamepad, TinyTextarea, TinyNewWinEvents, TinyIframeEvents, TinyLocalStorage, TinyTimeout, TinyColorConverter, TinyClipboard, TinyTextRangeEditor, TinySmartScroller, UltraRandomMsgGen, TinyAfterScrollWatcher, TinyHtml, TinyNotifications, TinyDomReadyManager, TinyDragger, TinyDragDropDetector, TinyToastNotify, TinyNotifyCenter, TinyRateLimiter, ColorSafeStringify, TinyPromiseQueue, TinyLevelUp, getYouTubeThumbnailUrl, fetchYouTubeOEmbed, extractYouTubeVideoId, assertYouTubeOEmbedResponse, createPluginIdChecker, verifyPluginSignature, signPluginIdentity, isClass, isAnyClassInstance, isClassInstance, isValidGlob, compileGlob, compileGlobRegExp, decompileGlob, isBrowser, emailStringRegexBuilder, emailRegex, isValidEmail, findEmailRegex, extractEmails, usernameStringRegexBuilder, usernameRegex, isValidUsername, findUsernameRegex, extractUsernames, urlStringRegexBuilder, urlRegex, isValidUrl, findUrlRegex, extractUrls, ipv6Regex, isValidIPv6, findIPv6Regex, extractIPsV6, ipv4Regex, isValidIPv4, findIPv4Regex, extractIPsV4, getObjTypeRegistry, getObjTypeOrder, segmentExtractorV1, makeSegmentExtractor, jsonFilter, jsonFilterRecursive, jsonFilterByKeys, getUserTimeFormat, getBrowserPings, isBrowserAgent, getBrowserCssPrefix, getDuckTyping, browserIs, isValidObj, createSingletonTask, waitForTrue, multiplyArrayBlocks, createCheckDestroyed, valMediaContentMetadata, valFetchMediaContent, parseMediaMetadata, extractMediaId3Tags, defuzzifyCentroid, trapezoid, diffArrayList, hashText, diffObjList, breakdownDuration, calculateMarketcap, compareMarketcap, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, isDirEmptyAsync, fileSizeAsync, dirSizeAsync, listFilesAsync, listDirsAsync, getLatestBackupPath, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, readJsonFile, writeJsonFile, ensureDirectory, clearDirectoryAsync, clearDirectory, fileExists, dirExists, isDirEmpty, ensureCopyFile, tryDeleteFile, writeTextFile, listFiles, listDirs, fileSize, dirSize, backupFile, restoreLatestBackup, renameFileBatch, renameFileRegex, renameFileAddPrefixSuffix, renameFileNormalizeCase, renameFilePadNumbers, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, checkObj, objTypeName, isObjType, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };
 //# sourceMappingURL=index.d.mts.map