tiny-essentials 1.28.18 → 1.29.0

package/dist/v1/libs/sw/service/plugins/TabManager.mjs

@@ -0,0 +1,372 @@
+import TinyPromiseQueue from '../../../utils/TinyPromiseQueue.mjs';
+import TinyServiceWorkerEngine from '../TinyServiceWorkerEngine.mjs';
+/** @type {ServiceWorkerGlobalScope} */
+// @ts-ignore
+export const sw = self;
+/** @typedef {import('../../../tools/TinyDebugger.mjs').DebuggerConstructor} DebuggerConstructor - The constructor function for a debugger instance. */
+/**
+ * Represents information about a single browser tab.
+ * @typedef {Object} TabInfo
+ * @property {string} id - The unique Client ID provided by the browser.
+ * @property {string} url - The current URL of the tab.
+ * @property {string} title - The document title of the tab.
+ * @property {boolean} isFocused - Whether the tab currently has window focus.
+ * @property {any} [data] - Custom data provided by the client.
+ */
+/**
+ * A mapping of unique tab IDs to their corresponding TabInfo objects.
+ * @typedef {Map<string, TabInfo>} TabInstance
+ */
+/**
+ * A layer within the TinyPlugin system specifically designed to manage and track tab instances.
+ */
+class TinySwTabsLayer extends TinyServiceWorkerEngine.TinyPluginLayer {
+    /**
+     * A queue used to manage and sequence asynchronous operations to prevent race conditions.
+     * @type {TinyPromiseQueue}
+     */
+    #queue = new TinyPromiseQueue();
+    /**
+     * Gets the internal promise queue instance.
+     * @returns {TinyPromiseQueue} - The instance of the promise queue.
+     */
+    get queue() {
+        return this.#queue;
+    }
+    /**
+     * A static registry that stores all active tab instances indexed by a unique key.
+     * @type {Map<number, TabInstance>}
+     */
+    static #instances = new Map();
+    /**
+     * A static counter used to assign unique keys to new TinySwTabsLayer instances.
+     * @type {number}
+     */
+    static #lastIndex = -1;
+    /**
+     * The unique identifier assigned to the current instance of the layer.
+     * @type {number}
+     */
+    #key;
+    /**
+     * A private Map storing the current session's tab information.
+     * @type {TabInstance}
+     */
+    #tabs = new Map();
+    /**
+     * A promise that resolves to the IndexedDB database instance.
+     * @type {Promise<IDBDatabase> | undefined}
+     */
+    #dbPromise;
+    /**
+     * Initializes the database connection for persistence.
+     * @returns {Promise<IDBDatabase>}
+     */
+    async #getDB() {
+        if (this.#dbPromise)
+            return this.#dbPromise;
+        this.#dbPromise = new Promise((resolve, reject) => {
+            const request = indexedDB.open('TinySwTabsDB', 1);
+            request.onupgradeneeded = () => {
+                request.result.createObjectStore('tabs');
+            };
+            request.onsuccess = () => resolve(request.result);
+            request.onerror = () => reject(request.error);
+        });
+        return this.#dbPromise;
+    }
+    /**
+     * Loads the tab registry from IndexedDB into the in-memory Map.
+     * @returns {Promise<void>}
+     */
+    async #loadFromStorage() {
+        const db = await this.#getDB();
+        return new Promise((resolve, reject) => {
+            const transaction = db.transaction('tabs', 'readonly');
+            const store = transaction.objectStore('tabs');
+            const request = store.getAll();
+            request.onsuccess = () => {
+                const data = request.result;
+                this.#tabs.clear();
+                // Data is stored as an array of TabInfo objects
+                data.forEach((tab) => {
+                    this.#tabs.set(tab.id, tab);
+                });
+                resolve();
+            };
+            request.onerror = () => reject(request.error);
+        });
+    }
+    /**
+     * Synchronizes the current in-memory Map with the IndexedDB storage.
+     * @returns {Promise<void>}
+     */
+    async persist() {
+        const db = await this.#getDB();
+        return this.#queue.enqueue(() => new Promise((resolve, reject) => {
+            const transaction = db.transaction('tabs', 'readwrite');
+            const store = transaction.objectStore('tabs');
+            // Clear existing registry to ensure deletions are reflected
+            store.clear();
+            for (const [id, tab] of this.#tabs.entries()) {
+                store.put(tab, id);
+            }
+            transaction.oncomplete = () => resolve();
+            transaction.onerror = () => reject(transaction.error);
+        }));
+    }
+    /**
+     * Retrieves a snapshot of all tabs currently managed by the instance corresponding to the provided key.
+     * @param {number} key - The unique key of the instance to retrieve tabs from.
+     * @returns {Record<string, TabInfo>|null} - An object mapping tab IDs to their information, or null if the instance is not found.
+     */
+    static getTabsInstance(key) {
+        const instance = TinySwTabsLayer.#instances.get(key);
+        if (!instance)
+            return null;
+        /** @type {Record<string, TabInfo>} */
+        const tabs = {};
+        instance.forEach((tab, key) => {
+            tabs[key] = { ...tab };
+        });
+        return tabs;
+    }
+    /**
+     * Retrieves the information for a specific tab by its unique ID.
+     * @param {string} id - The unique identifier of the tab.
+     * @returns {TabInfo|null} - The tab information if found, or null if the tab does not exist.
+     * @throws {TypeError} If the provided id is not a string.
+     * @throws {ReferenceError} If the internal layer instance cannot be found in the registry.
+     */
+    getTab(id) {
+        if (typeof id !== 'string') {
+            throw new TypeError('[TinySwTabsLayer] getTab: id must be a string.');
+        }
+        const instance = TinySwTabsLayer.#instances.get(this.#key);
+        if (!instance) {
+            throw new ReferenceError('[TinySwTabsLayer] Instance not found for the current key.');
+        }
+        const tab = instance.get(id);
+        if (!tab)
+            return null;
+        return { ...tab };
+    }
+    /**
+     * Initializes the layer, loads persisted data, and begins monitoring tab changes.
+     * @template {Parameters<TinySwTabsLayer['_startLayer']>[0]} Plugin - The TinyPlugin template.
+     * @param {Plugin} plugin - The TinyPlugin instance.
+     * @param {(tabs: TabInstance) => void} callback - The callback function to be executed with the current tabs upon initialization.
+     */
+    _start(plugin, callback) {
+        this.#queue.enqueue(() => this.#loadFromStorage());
+        return this._startLayer(plugin, callback, this.#tabs);
+    }
+    /**
+     * Initializes a new instance of the TinySwTabsLayer, assigning it a unique key and registering it in the static instances registry.
+     * @param {Partial<DebuggerConstructor>} [lgConfig] - Configuration options for the instance.
+     */
+    constructor(lgConfig = {}) {
+        super({
+            logCfg: {
+                id: '[_main_class_TinySW-Tabs_reset_]',
+                logger: lgConfig.logger ?? console,
+                debugMode: lgConfig.debugMode ?? false,
+                useLogColors: lgConfig.useLogColors ?? false,
+            },
+        });
+        TinySwTabsLayer.#lastIndex++;
+        TinySwTabsLayer.#instances.set(TinySwTabsLayer.#lastIndex, this.#tabs);
+        this.#key = TinySwTabsLayer.#lastIndex;
+    }
+}
+/**
+ * A plugin for TinyServiceWorkerEngine that manages a centralized registry of all open website tabs.
+ * @type {import('../TinyServiceWorkerEngine.mjs').SwPluginInstaller<TinySwTabsLayer, 'TabManager', '1.0.0', [Partial<DebuggerConstructor>]|[]>} - The plugin installer for the Tab Manager.
+ */
+const TinyTabManagerPlugin = (instance, lgConfig = {}) => {
+    const engine = instance.engine;
+    /**
+     * Stores permission settings per client ID.
+     * @type {Map<string, {allowFocusTracking: boolean, allowTabClosing: boolean}>}
+     */
+    const clientPermissions = new Map();
+    instance.id = 'TabManager';
+    instance.version = '1.0.0';
+    instance.description = 'Advanced tab manager.';
+    instance.authors = ['JasminDreasond'];
+    instance.contributors = ['JasminDreasond'];
+    instance.categories = ['tab-manager'];
+    instance.tags = ['management', 'consistency'];
+    instance.allowedGets = ['getTab'];
+    if (!(engine instanceof TinyServiceWorkerEngine)) {
+        throw new TypeError('Plugin requires a TinyServiceWorkerEngine instance to function.');
+    }
+    const layer = new TinySwTabsLayer(lgConfig);
+    layer._start(instance, (tabs) => {
+        /**
+         * Broadcasts the current list of tabs to all connected clients.
+         * @returns {Promise<void>}
+         */
+        const broadcastUpdate = async () => {
+            const tabList = {
+                count: tabs.size,
+                tabs: Array.from(tabs.values()),
+            };
+            // We use replyToAll to notify all clients that the list has changed.
+            await TinyServiceWorkerEngine.replyToAll({
+                type: 'tab:list_updated',
+                data: tabList,
+            });
+        };
+        /**
+         * Compares the in-memory tab registry with the actual browser clients.
+         * Removes any tabs that are no longer active in the browser.
+         * @returns {Promise<void>}
+         */
+        const reconcileTabs = async () => {
+            const activeClients = await layer.queue.enqueue(() => sw.clients.matchAll());
+            const activeIds = new Set(activeClients.map((client) => client.id));
+            let ghostFound = false;
+            for (const id of tabs.keys()) {
+                if (!activeIds.has(id)) {
+                    tabs.delete(id);
+                    ghostFound = true;
+                }
+            }
+            if (ghostFound) {
+                await layer.persist();
+                await broadcastUpdate();
+            }
+        };
+        // 1. Handle Tab Registration (When a new tab opens)
+        engine.onApi('tab:register', 
+        /**
+         * Processes registration messages to add new tabs to the registry.
+         */ async (msg) => {
+            const { data, clientId } = msg;
+            if (typeof clientId !== 'string') {
+                throw new TypeError('[TinyTabManagerPlugin] tab:register: clientId must be a string.');
+            }
+            if (typeof data?.url !== 'string' || typeof data?.title !== 'string') {
+                throw new TypeError('[TinyTabManagerPlugin] tab:register: data must contain url (string) and title (string).');
+            }
+            // Deep validation for permissions
+            if (data.permissions !== undefined) {
+                if (typeof data.permissions.allowFocusTracking !== 'boolean' ||
+                    typeof data.permissions.allowTabClosing !== 'boolean') {
+                    throw new TypeError('[TinyTabManagerPlugin] tab:register: data.permissions must contain allowFocusTracking (boolean) and allowTabClosing (boolean).');
+                }
+            }
+            // Store permissions sent by the client
+            clientPermissions.set(clientId, data.permissions ?? {
+                allowFocusTracking: true,
+                allowTabClosing: true,
+            });
+            // Perform reconciliation to clean up ghosts before adding new entries
+            await reconcileTabs();
+            tabs.set(clientId, {
+                id: clientId,
+                url: data.url,
+                title: data.title,
+                isFocused: data.isFocused,
+                data: data.data ?? null, // Capturing the custom cache data
+            });
+            await layer.persist(); // Persist to IndexedDB
+            await broadcastUpdate();
+        });
+        // 2. Single Tab Closing
+        engine.onApi('tab:close_single', async (msg) => {
+            if (!msg.data || typeof msg.data.id !== 'string') {
+                return { closed: false, reason: 'Invalid message data or missing string ID.' };
+            }
+            const { id } = msg.data;
+            // Check if the client has authorized tab closing
+            const permissions = clientPermissions.get(id);
+            if (permissions && !permissions.allowTabClosing) {
+                return { closed: false, reason: 'Permission denied by client.' };
+            }
+            const client = await sw.clients.get(id);
+            if (client) {
+                const response = await engine.emitApi(client, 'tab:close');
+                return { closed: !!response?.authorized };
+            }
+            return { closed: false };
+        });
+        // 3. Multiple Tab Closing
+        engine.onApi('tab:close_multiple', async (msg) => {
+            if (!msg.data || !Array.isArray(msg.data.ids)) {
+                throw new TypeError('[TinyTabManagerPlugin] tab:close_multiple: ids must be an array.');
+            }
+            const { ids } = msg.data;
+            const results = [];
+            for (const id of ids) {
+                if (typeof id !== 'string') {
+                    throw new TypeError('[TinyTabManagerPlugin] tab:close_multiple: invalid ID type in array.');
+                }
+                const permissions = clientPermissions.get(id);
+                if (permissions && !permissions.allowTabClosing) {
+                    results.push(-1);
+                    continue;
+                }
+                const client = await sw.clients.get(id);
+                if (client) {
+                    const response = await engine.emitApi(client, 'tab:close');
+                    results.push(!!response?.authorized ? 1 : 0);
+                }
+                else {
+                    results.push(0);
+                }
+            }
+            return { closed: results };
+        });
+        // 4. Close All Tabs
+        engine.onApi('tab:close_all', async () => {
+            const clients = await sw.clients.matchAll();
+            for (const client of clients) {
+                await engine.emitApi(client, 'tab:close');
+            }
+        });
+        // 5. Handle Tab Unregistration (When a tab is closed)
+        engine.onApi('tab:unregister', 
+        /**
+         * Processes unregistration messages to remove tabs from the registry.
+         */ async (msg) => {
+            const { clientId } = msg;
+            if (tabs.has(clientId)) {
+                tabs.delete(clientId);
+                await layer.persist(); // Persist to IndexedDB
+                await broadcastUpdate();
+            }
+            // Reconcile to ensure state consistency
+            await reconcileTabs();
+        });
+        // 6. Handle Request for current list (Manual polling)
+        engine.onApi('tab:get_list', 
+        /**
+         * Listens for requests to retrieve the current list of all registered tabs.
+         */ async () => {
+            // Ensure we are providing the most up-to-date list possible
+            await reconcileTabs();
+            // Reply directly to the source of the request
+            return { count: tabs.size, tabs: Array.from(tabs.values()) };
+        });
+        // 7. Handle Request for a specific tab
+        engine.onApi('tab:get_tab', 
+        /**
+         * Processes requests to retrieve information for a specific tab by its ID.
+         * @returns {Promise<TabInfo|undefined>} - The tab information or null if not found.
+         */ async (msg) => {
+            if (!msg.data)
+                return;
+            const { id } = msg.data;
+            if (typeof id !== 'string') {
+                throw new TypeError('[TinyTabManagerPlugin] tab:get_tab: data must contain id (string).');
+            }
+            const tab = tabs.get(id);
+            // Return a copy to prevent direct mutation of the registry
+            return tab ? { ...tab } : undefined;
+        });
+    });
+    return layer;
+};
+export default TinyTabManagerPlugin;

package/dist/v1/libs/sw/service/plugins/ViteFileDetector.cjs

@@ -0,0 +1,180 @@
+'use strict';
+
+var TinySetMapDatabase = require('../../../storage/TinySetMapDatabase.cjs');
+var TinyServiceWorkerEngine = require('../TinyServiceWorkerEngine.cjs');
+
+const { TinyPluginLayer } = TinyServiceWorkerEngine;
+
+const db = new TinySetMapDatabase.TinySetMapDatabase('tiny-sw-vite-file-detector', [
+  {
+    create: [
+      {
+        name: 'logged-urls',
+        validate: (value) => typeof value === 'string',
+        type: 'set',
+      },
+    ],
+  },
+]);
+
+/**
+ * Persistent store of URL strings that already emitted a detection log.
+ * Survives service worker restarts by mirroring every write into IndexedDB.
+ * @type {TinySetDb<string>}
+ */
+const loggedUrls = db.tableSet('logged-urls');
+
+/**
+ * Configuration options for the ViteFileDetectorPlugin to define which paths should be bypassed.
+ * @typedef {Object} ViteFileDetectorOptions
+ * @property {(string|RegExp)[]} paths - An array of strings or regular expressions used to identify URLs that should be bypassed.
+ * @property {string} srcPath - The base path for the source directory to be included in the bypass list.
+ * @property {string} manifestPath - The path to the manifest file to be included in the bypass list.
+ * @property {number} maxCachedUrls - Maximum amount of detected URLs kept in the persistent cache. When the limit is reached, the oldest entries are evicted before the new one is written. Use `Infinity` to keep every URL forever.
+ */
+
+/**
+ * Default configuration to maintain backward compatibility.
+ * @type {ViteFileDetectorOptions}
+ */
+const DEFAULT_OPTIONS = {
+  paths: ['/@vite', '/@react', '/node_modules'],
+  srcPath: '/src',
+  manifestPath: '/manifest.json',
+  maxCachedUrls: 1000,
+};
+
+/**
+ * A plugin for TinyServiceWorkerEngine to detect and bypass Vite-specific files.
+ *
+ * @type {import('../TinyServiceWorkerEngine.mjs').SwPluginInstaller<InstanceType<typeof TinyPluginLayer>, 'ViteFileDetector', '1.0.0', [Partial<ViteFileDetectorOptions>]|[]>}
+ * @throws {TypeError} If the engine is invalid or if the provided options do not match the required schema.
+ */
+const ViteFileDetectorPlugin = (instance, options = {}) => {
+  const engine = instance.engine;
+  instance.id = 'ViteFileDetector';
+  instance.version = '1.0.0';
+  instance.description = 'Vite File detector.';
+  instance.authors = ['JasminDreasond'];
+  instance.contributors = ['JasminDreasond'];
+  instance.categories = ['framework-validator'];
+  instance.tags = ['vite', 'framework', 'validator'];
+
+  if (!(engine instanceof TinyServiceWorkerEngine)) {
+    throw new TypeError('Plugin requires a TinyServiceWorkerEngine instance to function.');
+  }
+
+  // 1. Merge and Validate Options
+  /** @type {ViteFileDetectorOptions} */
+  const config = { ...DEFAULT_OPTIONS, ...options };
+
+  if (!Array.isArray(config.paths)) {
+    throw new TypeError('The "paths" property in options must be an array.');
+  }
+
+  const paths = [...config.paths, config.srcPath, config.manifestPath];
+
+  // Deep validation of the paths array elements
+  paths.forEach((pattern, index) => {
+    const isValidString = typeof pattern === 'string';
+    const isValidRegExp = pattern instanceof RegExp;
+
+    if (!isValidString && !isValidRegExp) {
+      throw new TypeError(
+        `Invalid type at paths[${index}]: Expected string or RegExp, but received ${typeof pattern}.`,
+      );
+    }
+  });
+
+  // 2. Validate the cache limit
+  if (typeof config.maxCachedUrls !== 'number') {
+    throw new TypeError(
+      `The "maxCachedUrls" option must be a number, but received ${typeof config.maxCachedUrls}.`,
+    );
+  }
+
+  if (
+    config.maxCachedUrls !== Infinity &&
+    (!Number.isInteger(config.maxCachedUrls) || config.maxCachedUrls < 1)
+  ) {
+    throw new RangeError(
+      `The "maxCachedUrls" option must be a positive integer or Infinity, but received ${config.maxCachedUrls}.`,
+    );
+  }
+
+  const { maxCachedUrls } = config;
+
+  // 3. Implementation
+  // @ts-ignore
+  if (undefined.DEV) {
+    /**
+     * Tail of the detection queue.
+     *
+     * Every cache mutation is chained here because `TinySetDb` only makes each
+     * individual call atomic. Without this queue, two detections that resolve in
+     * the same tick would both read the same `size` and both decide to insert,
+     * letting the cache grow past `maxCachedUrls`.
+     * @type {Promise<void>}
+     */
+    let detectionQueue = Promise.resolve();
+
+    /**
+     * Runs a detection task after every previously queued task has settled.
+     * @param {() => Promise<void>} task - The task that touches the cache.
+     * @returns {Promise<void>} Resolves when the task settles.
+     */
+    const enqueueDetection = (task) => {
+      const result = detectionQueue.then(task);
+      detectionQueue = result.catch(() => undefined);
+      return result;
+    };
+
+    /**
+     * Drops the oldest URLs until a single new entry fits inside the limit.
+     *
+     * The `+ 1` reserves the slot for the value that is about to be inserted,
+     * so the cache always ends up with exactly `maxCachedUrls` entries.
+     * @returns {Promise<void>} Resolves once the cache is below the limit.
+     */
+    const evictOldestUrls = async () => {
+      const overflow = loggedUrls.size - maxCachedUrls + 1;
+      if (overflow <= 0) return;
+
+      const snapshot = await loggedUrls.toArray();
+      /** @type {Promise<any>[]} */
+      const promises = [];
+      for (let index = 0; index < overflow; index += 1) {
+        promises.push(loggedUrls.delete(snapshot[index]));
+      }
+      await Promise.all(promises);
+    };
+
+    engine.addFetchGlobalListener('ViteFileDetectorPlugin', ({ url }, response) => {
+      const isBypassed = paths.some((pattern) => {
+        if (pattern instanceof RegExp) return pattern.test(url.pathname);
+        return url.pathname.startsWith(pattern);
+      });
+
+      if (!isBypassed) return;
+
+      response.continueCheck = false;
+      response.needValidation = false;
+      response.code = 200;
+
+      const cacheKey = url.toString();
+
+      enqueueDetection(async () => {
+        if (await loggedUrls.has(cacheKey)) return;
+        await evictOldestUrls();
+        await loggedUrls.add(cacheKey);
+        instance.log('warn', `File detected: ${cacheKey}`);
+      }).catch((error) => {
+        instance.log('error', `Failed to cache the detected URL "${cacheKey}": ${error.message}`);
+      });
+    });
+  }
+
+  return new TinyPluginLayer();
+};
+
+module.exports = ViteFileDetectorPlugin;

package/dist/v1/libs/sw/service/plugins/ViteFileDetector.d.mts

@@ -0,0 +1,28 @@
+declare const TinyPluginLayer: typeof import("../../../plugin/TinyPlugin.mjs").TinyPluginLayer;
+export type ViteFileDetectorOptions = {
+    /**
+     * - An array of strings or regular expressions used to identify URLs that should be bypassed.
+     */
+    paths: (string | RegExp)[];
+    /**
+     * - The base path for the source directory to be included in the bypass list.
+     */
+    srcPath: string;
+    /**
+     * - The path to the manifest file to be included in the bypass list.
+     */
+    manifestPath: string;
+    /**
+     * - Maximum amount of detected URLs kept in the persistent cache. When the limit is reached, the oldest entries are evicted before the new one is written. Use `Infinity` to keep every URL forever.
+     */
+    maxCachedUrls: number;
+};
+/**
+ * A plugin for TinyServiceWorkerEngine to detect and bypass Vite-specific files.
+ *
+ * @type {import('../TinyServiceWorkerEngine.mjs').SwPluginInstaller<InstanceType<typeof TinyPluginLayer>, 'ViteFileDetector', '1.0.0', [Partial<ViteFileDetectorOptions>]|[]>}
+ * @throws {TypeError} If the engine is invalid or if the provided options do not match the required schema.
+ */
+declare const ViteFileDetectorPlugin: import('../TinyServiceWorkerEngine.mjs').SwPluginInstaller<InstanceType<typeof TinyPluginLayer>, 'ViteFileDetector', '1.0.0', [Partial<ViteFileDetectorOptions>] | []>;
+export default ViteFileDetectorPlugin;
+//# sourceMappingURL=ViteFileDetector.d.mts.map

package/dist/v1/libs/sw/service/plugins/ViteFileDetector.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ViteFileDetector.d.mts","sourceRoot":"","sources":["../../../../../../../src/v1/libs/sw/service/plugins/ViteFileDetector.mjs"],"names":[],"mappings":"AAGA,QAAA,MAAQ,eAAe,iEAA4B,CAAC;AAuBjD,YAAkB,uBAAuB,GACzC;;;;IAA8B,KAAK,EAAxB,CAAC,MAAM,GAAC,MAAM,CAAC,EAAE,CAC5B;;;;IAAmB,OAAO,EAAf,MAAM,CACjB;;;;IAAmB,YAAY,EAApB,MAAM,CACjB;;;;IAAmB,aAAa,EAArB,MAAM,CACnB;CAAA,CAAA;AAaD;;;;;GAKG;AACH,QAAA,MAAM,sBAAsB,EAHlB,OAAO,gCAAgC,EAAE,iBAAiB,CAAC,YAAY,CAAC,OAAO,eAAe,CAAC,EAAE,kBAAkB,EAAE,OAAO,EAAE,CAAC,OAAO,CAAC,uBAAuB,CAAC,CAAC,GAAC,EAAE,CAgI5K,CAAC;eAEa,sBAAsB"}