@hkdigital/lib-sveltekit 0.1.68 → 0.1.70

package/dist/classes/cache/CacheStorage.js__

@@ -0,0 +1,45 @@
+/**
+ * @typedef {Object} CacheEntry
+ * @property {Response} response The cached response
+ * @property {Object} metadata Cache metadata including expiration
+ * @property {string} url The request URL
+ * @property {number} timestamp When the entry was cached
+ * @property {number|null} expires When the entry expires
+ * @property {string|null} etag ETag for conditional requests
+ * @property {string|null} lastModified Last-Modified for conditional requests
+ */
+
+/**
+ * Cache Storage Interface
+ * @interface
+ */
+class CacheStorage {
+  /**
+   * Get a cached response for a key
+   * @param {string} key Cache key
+   * @returns {Promise<CacheEntry|null>} Cached response or null if not found
+   */
+  async get(key) { throw new Error('Not implemented'); }
+  
+  /**
+   * Store a response in the cache
+   * @param {string} key Cache key
+   * @param {Response} response Response to cache
+   * @param {Object} metadata Cache metadata
+   * @returns {Promise<void>}
+   */
+  async set(key, response, metadata) { throw new Error('Not implemented'); }
+  
+  /**
+   * Remove a cached response
+   * @param {string} key Cache key
+   * @returns {Promise<boolean>} True if entry was removed
+   */
+  async delete(key) { throw new Error('Not implemented'); }
+  
+  /**
+   * Clear all cached responses
+   * @returns {Promise<void>}
+   */
+  async clear() { throw new Error('Not implemented'); }
+}

package/dist/classes/cache/MemoryResponseCache.d.ts

@@ -0,0 +1,19 @@
+/**
+ * ReponseCache
+ * Using in-memory storage
+ */
+export default class MemoryResponseCache {
+    cache: Map<any, any>;
+    get(key: any): Promise<{
+        response: any;
+        metadata: any;
+        url: any;
+        timestamp: any;
+        expires: any;
+        etag: any;
+        lastModified: any;
+    }>;
+    set(key: any, response: any, metadata: any): Promise<void>;
+    delete(key: any): Promise<boolean>;
+    clear(): Promise<void>;
+}

package/dist/classes/cache/MemoryResponseCache.js

@@ -0,0 +1,53 @@
+/**
+ * ReponseCache
+ * Using in-memory storage
+ */
+export default class MemoryResponseCache {
+  constructor() {
+    this.cache = new Map();
+  }
+  
+  async get(key) {
+    const entry = this.cache.get(key);
+    
+    if (!entry) {
+      return null;
+    }
+    
+    // Check if expired
+    if (entry.expires && Date.now() > entry.expires) {
+      this.delete(key);
+      return null;
+    }
+    
+    return {
+      response: entry.response.clone(),
+      metadata: entry.metadata,
+      url: entry.url,
+      timestamp: entry.timestamp,
+      expires: entry.expires,
+      etag: entry.etag,
+      lastModified: entry.lastModified
+    };
+  }
+  
+  async set(key, response, metadata) {
+    this.cache.set(key, {
+      response: response.clone(),
+      metadata,
+      url: response.url,
+      timestamp: Date.now(),
+      expires: metadata.expires || null,
+      etag: response.headers.get('ETag'),
+      lastModified: response.headers.get('Last-Modified')
+    });
+  }
+  
+  async delete(key) {
+    return this.cache.delete(key);
+  }
+  
+  async clear() {
+    this.cache.clear();
+  }
+}

package/dist/classes/cache/PersistentResponseCache.d.ts

@@ -0,0 +1,46 @@
+/**
+ * ReponseCache
+ * Using IndexedDB for persistent storage
+ */
+export default class ResponseCache {
+    /**
+     * Create a new IndexedDB cache storage
+     * @param {string} dbName Database name
+     * @param {string} storeName Store name
+     */
+    constructor(dbName?: string, storeName?: string);
+    dbName: string;
+    storeName: string;
+    dbPromise: Promise<IDBDatabase>;
+    /**
+     * Open the IndexedDB database
+     * @private
+     * @returns {Promise<IDBDatabase>}
+     */
+    private _openDatabase;
+    /**
+     * Get a cached response
+     * @param {string} key Cache key
+     * @returns {Promise<import('./typedef').CacheEntry|null>}
+     */
+    get(key: string): Promise<import("./typedef").CacheEntry | null>;
+    /**
+     * Store a response in the cache
+     * @param {string} key Cache key
+     * @param {Response} response Response to cache
+     * @param {Object} metadata Cache metadata
+     * @returns {Promise<void>}
+     */
+    set(key: string, response: Response, metadata: any): Promise<void>;
+    /**
+     * Delete a cached response
+     * @param {string} key Cache key
+     * @returns {Promise<boolean>}
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Clear all cached responses
+     * @returns {Promise<void>}
+     */
+    clear(): Promise<void>;
+}

package/dist/classes/cache/PersistentResponseCache.js

@@ -0,0 +1,165 @@
+
+
+/**
+ * ReponseCache
+ * Using IndexedDB for persistent storage
+ */
+export default class ResponseCache {
+  /**
+   * Create a new IndexedDB cache storage
+   * @param {string} dbName Database name
+   * @param {string} storeName Store name
+   */
+  constructor(dbName = 'http-cache', storeName = 'responses') {
+    this.dbName = dbName;
+    this.storeName = storeName;
+    this.dbPromise = this._openDatabase();
+  }
+  
+  /**
+   * Open the IndexedDB database
+   * @private
+   * @returns {Promise<IDBDatabase>}
+   */
+  async _openDatabase() {
+    return new Promise((resolve, reject) => {
+      const request = indexedDB.open(this.dbName, 1);
+      
+      request.onerror = () => reject(request.error);
+      request.onsuccess = () => resolve(request.result);
+      
+      request.onupgradeneeded = (event) => {
+        const db = event.target.result;
+        if (!db.objectStoreNames.contains(this.storeName)) {
+          db.createObjectStore(this.storeName, { keyPath: 'key' });
+        }
+      };
+    });
+  }
+  
+  /**
+   * Get a cached response
+   * @param {string} key Cache key
+   * @returns {Promise<import('./typedef').CacheEntry|null>}
+   */
+  async get(key) {
+    const db = await this.dbPromise;
+    
+    return new Promise((resolve, reject) => {
+      const transaction = db.transaction(this.storeName, 'readonly');
+      const store = transaction.objectStore(this.storeName);
+      const request = store.get(key);
+      
+      request.onerror = () => reject(request.error);
+      request.onsuccess = () => {
+        const entry = request.result;
+        
+        if (!entry) {
+          resolve(null);
+          return;
+        }
+        
+        // Check if expired
+        if (entry.expires && Date.now() > entry.expires) {
+          // Delete expired entry
+          this.delete(key).catch(console.error);
+          resolve(null);
+          return;
+        }
+        
+        // Deserialize the response
+        const response = new Response(entry.body, {
+          status: entry.status,
+          statusText: entry.statusText,
+          headers: new Headers(entry.headers)
+        });
+        
+        resolve({
+          response,
+          metadata: entry.metadata,
+          url: entry.url,
+          timestamp: entry.timestamp,
+          expires: entry.expires,
+          etag: entry.etag,
+          lastModified: entry.lastModified
+        });
+      };
+    });
+  }
+  
+  /**
+   * Store a response in the cache
+   * @param {string} key Cache key
+   * @param {Response} response Response to cache
+   * @param {Object} metadata Cache metadata
+   * @returns {Promise<void>}
+   */
+  async set(key, response, metadata) {
+    const db = await this.dbPromise;
+    
+    // Clone the response to avoid consuming it
+    const clonedResponse = response.clone();
+    
+    // Extract response data
+    const body = await clonedResponse.blob();
+    const headers = Array.from(clonedResponse.headers.entries());
+    
+    const entry = {
+      key,
+      url: clonedResponse.url,
+      status: clonedResponse.status,
+      statusText: clonedResponse.statusText,
+      headers,
+      body,
+      metadata,
+      timestamp: Date.now(),
+      expires: metadata.expires || null,
+      etag: clonedResponse.headers.get('ETag'),
+      lastModified: clonedResponse.headers.get('Last-Modified')
+    };
+    
+    return new Promise((resolve, reject) => {
+      const transaction = db.transaction(this.storeName, 'readwrite');
+      const store = transaction.objectStore(this.storeName);
+      const request = store.put(entry);
+      
+      request.onerror = () => reject(request.error);
+      request.onsuccess = () => resolve();
+    });
+  }
+  
+  /**
+   * Delete a cached response
+   * @param {string} key Cache key
+   * @returns {Promise<boolean>}
+   */
+  async delete(key) {
+    const db = await this.dbPromise;
+    
+    return new Promise((resolve, reject) => {
+      const transaction = db.transaction(this.storeName, 'readwrite');
+      const store = transaction.objectStore(this.storeName);
+      const request = store.delete(key);
+      
+      request.onerror = () => reject(request.error);
+      request.onsuccess = () => resolve(true);
+    });
+  }
+  
+  /**
+   * Clear all cached responses
+   * @returns {Promise<void>}
+   */
+  async clear() {
+    const db = await this.dbPromise;
+    
+    return new Promise((resolve, reject) => {
+      const transaction = db.transaction(this.storeName, 'readwrite');
+      const store = transaction.objectStore(this.storeName);
+      const request = store.clear();
+      
+      request.onerror = () => reject(request.error);
+      request.onsuccess = () => resolve();
+    });
+  }
+}

package/dist/classes/cache/index.d.ts

@@ -0,0 +1,3 @@
+export { default as MemoryResponseCache } from "./MemoryResponseCache.js";
+export { default as PersistentResponseCache } from "./PersistentResponseCache.js";
+export * from "./typedef.js";

package/dist/classes/cache/index.js

@@ -0,0 +1,5 @@
+
+export { default as MemoryResponseCache } from "./MemoryResponseCache.js";
+export { default as PersistentResponseCache } from "./PersistentResponseCache.js";
+
+export * from './typedef.js';

package/dist/classes/cache/typedef.d.ts

@@ -0,0 +1,50 @@
+declare const _default: {};
+export default _default;
+export type CacheEntry = {
+    /**
+     * The cached response
+     */
+    response: Response;
+    /**
+     * Cache metadata including expiration
+     */
+    metadata: any;
+    /**
+     * The request URL
+     */
+    url: string;
+    /**
+     * When the entry was cached
+     */
+    timestamp: number;
+    /**
+     * When the entry expires
+     */
+    expires: number | null;
+    /**
+     * ETag for conditional requests
+     */
+    etag: string | null;
+    /**
+     * Last-Modified for conditional requests
+     */
+    lastModified: string | null;
+};
+export type CacheStorage = {
+    /**
+     *   Get a cached response for a key
+     */
+    get: (arg0: string) => Promise<CacheEntry | null>;
+    /**
+     *   Store a response in the cache
+     */
+    set: (arg0: string, arg1: Response, arg2: any) => Promise<void>;
+    /**
+     *   Remove a cached response
+     */
+    delete: (arg0: string) => Promise<boolean>;
+    /**
+     *   Clear all cached responses
+     */
+    clear: () => Promise<void>;
+};

package/dist/classes/cache/typedef.js

@@ -0,0 +1,25 @@
+
+/**
+ * @typedef {Object} CacheEntry
+ * @property {Response} response The cached response
+ * @property {Object} metadata Cache metadata including expiration
+ * @property {string} url The request URL
+ * @property {number} timestamp When the entry was cached
+ * @property {number|null} expires When the entry expires
+ * @property {string|null} etag ETag for conditional requests
+ * @property {string|null} lastModified Last-Modified for conditional requests
+ */
+
+/**
+ * @typedef {Object} CacheStorage
+ * @property {function(string): Promise<CacheEntry|null>} get
+ *   Get a cached response for a key
+ * @property {function(string, Response, Object): Promise<void>} set
+ *   Store a response in the cache
+ * @property {function(string): Promise<boolean>} delete
+ *   Remove a cached response
+ * @property {function(): Promise<void>} clear
+ *   Clear all cached responses
+ */
+
+export default {};

package/dist/util/http/caching.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Store a response in the cache
+ *
+ * @param {object} cacheKeyParams - Parameters to use for cache key generation
+ * @param {string|URL} cacheKeyParams.url - URL string or URL object
+ * @param {object} [cacheKeyParams.headers] - Request headers that affect caching
+ * @param {Response} response - Response to cache
+ * @param {object} metadata - Cache metadata
+ * @returns {Promise<void>}
+ */
+export function storeResponseInCache(cacheKeyParams: {
+    url: string | URL;
+    headers?: object;
+}, response: Response, metadata: object): Promise<void>;
+/**
+ * Get a cached response if available and valid
+ *
+ * @param {object} cacheKeyParams - Parameters to use for cache key generation
+ * @param {string|URL} cacheKeyParams.url - URL string or URL object
+ * @param {object} [cacheKeyParams.headers] - Request headers that affect caching
+ *
+ * @returns {Promise<Response|import('./typedef').ResponseWithStale|null>}
+ *   Cached response or null
+ */
+export function getCachedResponse(cacheKeyParams: {
+    url: string | URL;
+    headers?: object;
+}): Promise<Response | import("./typedef").ResponseWithStale | null>;

package/dist/util/http/caching.js

@@ -0,0 +1,251 @@
+import {
+  MemoryResponseCache,
+  PersistentResponseCache
+} from '../../classes/cache';
+
+let defaultCacheStorage = null;
+
+function getCacheStorage()
+{
+  if( !defaultCacheStorage )
+  {
+    defaultCacheStorage =
+      createCacheStorage(
+        process.env.NODE_ENV === 'test' ? 'memory' : 'persistent'
+      );
+  }
+
+  return defaultCacheStorage
+}
+
+/**
+ * Store a response in the cache
+ *
+ * @param {object} cacheKeyParams - Parameters to use for cache key generation
+ * @param {string|URL} cacheKeyParams.url - URL string or URL object
+ * @param {object} [cacheKeyParams.headers] - Request headers that affect caching
+ * @param {Response} response - Response to cache
+ * @param {object} metadata - Cache metadata
+ * @returns {Promise<void>}
+ */
+export async function storeResponseInCache(cacheKeyParams, response, metadata) {
+  try {
+    const { url: rawUrl, ...headers } = cacheKeyParams;
+    const url = typeof rawUrl === 'string' ? rawUrl : rawUrl.toString();
+
+    // Generate cache key
+    const cacheKey = generateCacheKey(url, headers);
+
+    // Extract Vary header info
+    const varyHeader = response.headers.get('Vary');
+    let varyHeaders = null;
+
+    if (varyHeader) {
+      varyHeaders = {};
+      const varyFields = varyHeader.split(',').map(field => field.trim().toLowerCase());
+
+      // Store hashes of headers mentioned in Vary
+      for (const field of varyFields) {
+        if (field !== '*') {
+          const value = headers[field];
+          varyHeaders[field] = hashValue(value);
+        }
+      }
+    }
+
+    // Add vary headers to metadata
+    const enhancedMetadata = {
+      ...metadata,
+      varyHeaders
+    };
+
+    // Store in cache
+    await getCacheStorage().set(cacheKey, response, enhancedMetadata);
+  } catch (error) {
+    console.error('Cache storage error:', error);
+  }
+}
+
+/**
+ * Get a cached response if available and valid
+ *
+ * @param {object} cacheKeyParams - Parameters to use for cache key generation
+ * @param {string|URL} cacheKeyParams.url - URL string or URL object
+ * @param {object} [cacheKeyParams.headers] - Request headers that affect caching
+ *
+ * @returns {Promise<Response|import('./typedef').ResponseWithStale|null>}
+ *   Cached response or null
+ */
+export async function getCachedResponse(cacheKeyParams) {
+  try {
+    const { url: rawUrl, ...headers } = cacheKeyParams;
+    const url = typeof rawUrl === 'string' ? rawUrl : rawUrl.toString();
+
+    // Generate cache key
+    const cacheKey = generateCacheKey(url, headers);
+
+    // Get cached entry
+    const cachedEntry = await getCacheStorage().get(cacheKey);
+
+    if (!cachedEntry) {
+      return null;
+    }
+
+    // Validate based on Vary headers
+    if (!isValidForVaryHeaders(cachedEntry, headers)) {
+      return null;
+    }
+
+    const { response, metadata } = cachedEntry;
+
+    // Check if expired
+    const isExpired = metadata.expires && Date.now() > metadata.expires;
+
+    if (!isExpired) {
+      // Not expired, return as-is
+      return response;
+    }
+
+    // Response is stale, add stale info
+    return enhanceResponseWithStale(response, {
+      isStale: true,
+      fresh: null,  // No fresh data available yet
+      timestamp: metadata.timestamp,
+      expires: metadata.expires
+    });
+  } catch (error) {
+    console.error('Cache retrieval error:', error);
+    return null;
+  }
+}
+
+// > Internal functions
+
+/**
+ * Create a cache storage adapter
+ * @param {string} type Type of storage ('persistent', 'memory')
+ * @param {Object} options Options for the storage adapter
+ *
+ * @returns {import('../../classes/cache').CacheStorage}
+ */
+function createCacheStorage(type = 'persistent', options = {}) {
+  switch (type) {
+    case 'persistent':
+      return new PersistentResponseCache(
+        options.dbName || 'http-cache',
+        options.storeName || 'responses'
+      );
+
+    case 'memory':
+      return new MemoryResponseCache();
+
+    default:
+      throw new Error(`Unsupported cache storage type: ${type}`);
+  }
+}
+
+/**
+ * Check if cached entry is valid based on Vary headers
+ *
+ * @param {object} cachedEntry - Cached entry with response and metadata
+ * @param {object} headers - Current request headers
+ * @returns {boolean} True if valid for these headers
+ */
+function isValidForVaryHeaders(cachedEntry, headers) {
+  const { metadata } = cachedEntry;
+
+  // If no vary headers stored, consider valid
+  if (!metadata.varyHeaders) {
+    return true;
+  }
+
+  // Check each stored vary header
+  for (const [name, storedHash] of Object.entries(metadata.varyHeaders)) {
+    const currentValue = headers[name];
+    const currentHash = hashValue(currentValue);
+
+    // Compare hashes
+    if (currentHash !== storedHash) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Generate a cache key based on URL and relevant headers
+ *
+ * @param {string} url - URL string
+ * @param {object} headers - Request headers
+ * @returns {string} Cache key
+ */
+function generateCacheKey(url, headers) {
+  // Start with a hash of the URL
+  const keyParts = [hashValue(url)];
+
+  // If we have headers
+  if (headers && Object.keys(headers).length > 0) {
+    // Get all header names, sorted for consistency
+    const headerNames = Object.keys(headers).sort();
+
+    // Create a hash for each header value
+    const headerHashes = headerNames.map(name => {
+      const value = headers[name];
+      // Format: "name:hash_of_value"
+      return `${name}:${hashValue(value)}`;
+    });
+
+    if (headerHashes.length > 0) {
+      keyParts.push(headerHashes.join('|'));
+    }
+  }
+
+  return keyParts.join('::');
+}
+
+/**
+ * Create a hash of a value
+ *
+ * @param {string} value - Value to hash
+ * @returns {string} Hash representation
+ */
+function hashValue(value) {
+  if (!value) return '';
+
+  // Convert to string if not already
+  const stringValue = String(value);
+
+  // Simple non-cryptographic hash function
+  let hash = 0;
+  for (let i = 0; i < stringValue.length; i++) {
+    const char = stringValue.charCodeAt(i);
+    hash = ((hash << 5) - hash) + char;
+    hash = hash & hash; // Convert to 32bit integer
+  }
+  return hash.toString(16); // Convert to hex
+}
+
+
+/**
+ * Enhance a Response object with stale data properties
+ *
+ * @param {Response} response - The original Response object
+ * @param {import('./typedef').StaleInfo} staleInfo - Stale data information
+ *
+ * @returns {import('./typedef').ResponseWithStale}
+ *   Enhanced response with stale data properties
+ */
+function enhanceResponseWithStale(response, staleInfo) {
+  // Create a new object that inherits from Response prototype
+  const enhanced = Object.create(
+    Object.getPrototypeOf(response),
+    Object.getOwnPropertyDescriptors(response)
+  );
+
+  // Add stale properties
+  enhanced.isStale = staleInfo.isStale || false;
+  enhanced.fresh = staleInfo.fresh || null;
+
+  return enhanced;
+}