@xiboplayer/cache 0.1.3 → 0.3.0

package/README.md

@@ -0,0 +1,50 @@
+# @xiboplayer/cache
+
+**Offline caching and download management with parallel chunk downloads.**
+
+## Overview
+
+Manages media downloads and offline storage for Xibo players:
+
+- **Parallel chunk downloads** — large files (100MB+) split into configurable chunks, downloaded concurrently
+- **Header+trailer first** — MP4 moov atom fetched first for instant playback start before full download
+- **MD5 verification** — integrity checking with CRC32-based skip optimization
+- **Download queue** — flat queue with barriers for layout-ordered downloading
+- **CacheProxy** — browser-side proxy that communicates with a Service Worker backend
+
+## Installation
+
+```bash
+npm install @xiboplayer/cache
+```
+
+## Usage
+
+```javascript
+import { CacheProxy } from '@xiboplayer/cache';
+
+const cache = new CacheProxy();
+await cache.init();
+
+// Request downloads (delegated to Service Worker)
+await cache.requestDownload({ layoutOrder, files });
+
+// Check if a file is cached
+const isCached = await cache.has(fileId);
+```
+
+## Exports
+
+| Export | Description |
+|--------|-------------|
+| `CacheProxy` | Browser-side proxy communicating with SW backend |
+| `DownloadManager` | Core download queue with barrier-based ordering |
+
+## Dependencies
+
+- `@xiboplayer/utils` — logger, events
+- `spark-md5` — MD5 hashing for file verification
+
+---
+
+**Part of the [XiboPlayer SDK](https://github.com/linuxnow/xiboplayer)**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiboplayer/cache",
-  "version": "0.1.3",
+  "version": "0.3.0",
   "description": "Offline caching and download management with parallel chunk downloads",
   "type": "module",
   "main": "./src/index.js",
@@ -12,7 +12,7 @@
   },
   "dependencies": {
     "spark-md5": "^3.0.2",
-    "@xiboplayer/utils": "0.1.3"
+    "@xiboplayer/utils": "0.3.0"
   },
   "devDependencies": {
     "vitest": "^2.0.0",

package/src/cache-proxy.js

@@ -170,14 +170,19 @@ class ServiceWorkerBackend extends EventEmitter {
 
   /**
    * Request downloads from Service Worker (non-blocking)
-   * @param {Array} files - Array of { id, type, path, md5 }
+   * @param {Object|Array} payload - Either { layouts: [{ layoutId, mediaFiles }] } or flat Array of files
    * @returns {Promise<void>}
    */
-  async requestDownload(files) {
+  async requestDownload(payload) {
     if (!this.controller) {
       throw new Error('Service Worker not available');
     }
 
+    // Support both grouped and flat payload (backward compat)
+    const data = Array.isArray(payload)
+      ? { files: payload }
+      : payload;
+
     return new Promise((resolve, reject) => {
       const messageChannel = new MessageChannel();
 
@@ -195,7 +200,7 @@ class ServiceWorkerBackend extends EventEmitter {
       this.controller.postMessage(
         {
           type: 'DOWNLOAD_FILES',
-          data: { files }
+          data
         },
         [messageChannel.port2]
       );
@@ -222,20 +227,13 @@ class ServiceWorkerBackend extends EventEmitter {
   }
 
   /**
-   * Check if file is cached
+   * Check if file is cached (delegates to hasFile for consistent fetchReady handling)
    * @param {string} type - 'media', 'layout', 'widget'
    * @param {string} id - File ID
    * @returns {Promise<boolean>}
    */
   async isCached(type, id) {
-    const cacheUrl = `${BASE}/cache/${type}/${id}`;
-
-    try {
-      const response = await fetch(cacheUrl, { method: 'HEAD' });
-      return response.ok;
-    } catch (error) {
-      return false;
-    }
+    return this.hasFile(type, id);
   }
 
   /**
@@ -384,16 +382,13 @@ export class CacheProxy extends EventEmitter {
   }
 
   /**
-   * Check if file is cached
+   * Check if file is cached (delegates to hasFile for consistent fetchReady handling)
    * @param {string} type - 'media', 'layout', 'widget'
    * @param {string} id - File ID
    * @returns {Promise<boolean>}
    */
   async isCached(type, id) {
-    if (!this.backend) {
-      throw new Error('CacheProxy not initialized');
-    }
-    return await this.backend.isCached(type, id);
+    return this.hasFile(type, id);
   }
 
   /**

package/src/cache.test.js

@@ -217,7 +217,7 @@ describe('CacheManager', () => {
     beforeEach(async () => {
       await manager.init();
 
-      // Helper: create a mock blob with arrayBuffer() support
+      // Helper: create a mock blob with arrayBuffer()/stream() support
       function createMockBlob(content, type) {
         const blob = new Blob([content], { type });
         // Polyfill arrayBuffer() for jsdom environments that lack it
@@ -230,6 +230,15 @@ describe('CacheManager', () => {
             });
           };
         }
+        // Polyfill stream() for jsdom environments that lack it
+        if (!blob.stream) {
+          blob.stream = () => new ReadableStream({
+            start(controller) {
+              controller.enqueue(new TextEncoder().encode(content));
+              controller.close();
+            }
+          });
+        }
         return blob;
       }
 
@@ -516,7 +525,8 @@ describe('CacheManager', () => {
 
       const retrieved = await manager.getCachedFile('media', '1');
 
-      expect(retrieved).toBeInstanceOf(Blob);
+      expect(retrieved).toBeTruthy();
+      expect(retrieved.size).toBeGreaterThan(0);
     });
 
     it('should return null for non-cached file', async () => {