feat: Add caching module for YouTube video info

[mitsuki31]

Overview

This pull request introduces a new caching module to optimize the retrieval of YouTube video information. By implementing a local caching mechanism, the system avoids repetitive fetch requests to YouTube servers, resulting in significant performance improvements.

Changes Made

Features

• Added a new VInfoCache class to handle caching of video information, including creation, validation, and retrieval.
• Introduced utility classes CacheBase64 and CacheZLib for encoding, decoding, compressing, and decompressing cache objects.
• Defined constants for cache directory paths (CACHE_PATH, VINFO_CACHE_PATH).
• Implemented utility functions for cache path generation and ID validation.
• Introduced a humanReadable option to VInfoCache.getCache and VInfoCache.getAllCaches for better presentation of cache data.
• Added a createdDate property to cache objects to indicate the creation timestamp.
• Implemented VInfoCache.deleteCache for cache deletion.
• Introduced a new error class called CacheValidationError to handle invalid cache objects with detailed contextual information (e.g., cache ID, type, and path).

Implementation

VInfoCache:

class VInfoCache {
  static function createCache(
    videoInfo: ytdl.VideoInfo,
    cacheOptions?: { cacheDir?: string }
  ): Promise<string>;
  static function getCache(
    videoId: string,
    cacheOptions?: {
      cacheDir?: string,
      humanReadable?: boolean,
      validate?: boolean
    }
  ): Promise<ExtractedVideoInfoCacheObject | string | null>;
  static function getAllCaches(
    cacheOptions?: {
      cacheDir?: string,
      humanReadable?: boolean,
      validate?: boolean
    }
  ): Promise<ExtractedVideoInfoCacheObject[] | string>;
  static function deleteCache(
    videoId: string,
    cacheOptions?: { cacheDir?: string }
  ): Promise<boolean>;
}

CacheBase64:

class CacheBase64 {
  static function encodeCacheObject(
    obj: Record<string, unknown>
  ): string;
  static function decodeCacheObject(
    encodedStr: string
  ): Record<string, unknown>;
}

CacheZLib:

class CacheZLib {
  static function deflateCacheObject(
    obj: Record<string, unknown>
  ): Promise<Buffer>;
  static function inflateCacheObject(
    deflatedObj: Record<'type' | 'data', string>
  ): Promise<Record<string, unknown>>;
}

---

Testing

• Comprehensive unit tests for CacheBase64, CacheZLib, VInfoCache, and utility functions.
• Validation scenarios for handling invalid caches, including the new CacheValidationError.
• Added test coverage for new features like cache deletion and the humanReadable option.

Documentation

• Updated JSDoc for all new and modified methods.
• Declared a new typedef, VideoInfoCacheObject, to represent the cache data structure.
• Declared a new typedef, ExtractedVideoInfoCacheObject, to represent parsed and extracted cache data.

Cache Structure

The cache structure is as follows:

{
  "id": "<videoId>",
  "encoding": "binary",
  "createdDate": "<timestamp>",
  "title": "<videoTitle>",
  "authorName": "<authorName>",
  "videoUrl": "https://www.youtube.com/watch?v=<videoId>",
  "authorUrl": "https://www.youtube.com/<@username>",
  "videoInfo": {
    "type": "zlib/bin",
    "data": "<compressedBinaryCacheData>"
  }
}

TypeScript:

interface VideoInfoCacheObject {
  id: string;
  encoding: 'binary';
  createdDate: number;
  title: string;
  authorName: string;
  videoUrl: string;
  authorUrl: string;
  videoInfo: {
    type: 'zlib/bin';
    data: string;
  };
}

Details

Property	Description
id	Unique identifier for the video.
encoding	Encoding format of the cache data, typically "binary".
createdDate	Timestamp indicating when the cache was created (returned from Date.now()).
title	Title of the video or "<unknown>" if not available.
authorName	Name of the author of the video or "<unknown>" if not available.
videoUrl	URL of the video.
authorUrl	URL of the author of the video (refers to author profile).
videoInfo	Object containing the compressed and binary encoded video information.
videoInfo.type	Type of the video information, typically "zlib/bin".
videoInfo.data	Compressed and binary encoded video information data.

Usage Examples

Please take note first, that the cache utilities are intended for internal use.

// ...

const videoInfo = // assume you have a valid `videoInfo` object

// Create a cache object
const cachePath = await VInfoCache.createCache(videoInfo, {
  cachePath: undefined // path to custom cache directory, if needed
});
console.log(`Cache created at: ${cachePath}`);

// Get a cache object
const cachedInfo = await VInfoCache.getCache(videoId, {
  cachePath: undefined // custom directory path to locate the cache, if needed
});
if (cachedInfo) {
  console.log('Cached video info:', cachedInfo);
} else {
  console.log('No cache found for video ID:', videoId);
}

Impact

• Improves system performance by reducing repetitive server fetches through caching.
• Provides better error handling and validation for cache data integrity.
• Enhances developer usability with detailed documentation, flexible options, and human-readable formats for cache data.
• Introduces efficient cache management through deletion and comprehensive test coverage.

Summary

This PR establishes the foundation for a robust caching mechanism that enhances both performance and usability for video information handling. The changes ensure better scalability and reliability while adhering to high standards of code quality and maintainability.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 83.16%. Comparing base (560887d) to head (de128b9).
Report is 16 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master      #96      +/-   ##
==========================================
+ Coverage   80.36%   83.16%   +2.80%     
==========================================
  Files          11       12       +1     
  Lines         611      713     +102     
==========================================
+ Hits          491      593     +102     
  Misses        120      120              

Flag	Coverage Δ
Ubuntu	83.16% <100.00%> (+2.80%)	⬆️
Windows	82.88% <100.00%> (+2.85%)	⬆️
all	83.16% <100.00%> (+2.80%)	⬆️
macOS	83.16% <100.00%> (+2.80%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[mitsuki31]

These changes are only the cache module implementation. Integrating to the core module (ytmp3.js) is still in development and may need a huge refactor into existing features.

[mitsuki31]

Cache module recently updated and comes with a new feature to force the cache creation. Refer to #98 for more details.

cacheOptions: {
  cacheDir?: string,
  force?: boolean
}