Aprovechando la API de Acceso al Sistema de Archivos en PWAs: Persistencia Avanzada

🚀 Introducción a la API de Acceso al Sistema de Archivos en PWAs

Las Progressive Web Apps (PWAs) han revolucionado la forma en que pensamos sobre las aplicaciones web, difuminando la línea entre el navegador y el escritorio. Sin embargo, una limitación persistente para muchas PWAs ha sido su incapacidad para interactuar directamente con el sistema de archivos del usuario de la misma manera que lo hacen las aplicaciones nativas. Aquí es donde entra en juego la API de Acceso al Sistema de Archivos (File System Access API), una poderosa adición que permite a las PWAs leer, escribir y gestionar archivos y directorios en el sistema local del usuario con su consentimiento.

Esta API abre un mundo de posibilidades para aplicaciones web que necesitan manejar documentos, imágenes, audio, video y otros tipos de datos de forma local y persistente, sin la necesidad de subidas y descargas constantes a un servidor. Imagina un editor de texto en línea que guarda directamente en tu carpeta de Documentos, o una aplicación de edición de imágenes que abre y guarda fotos sin intermediarios.

En este tutorial, exploraremos los fundamentos de esta API, cómo implementarla en tus PWAs y las consideraciones clave para ofrecer una experiencia de usuario segura y robusta.

¿Por qué es Crucial la API de Acceso al Sistema de Archivos para PWAs? 🤔

Tradicionalmente, las aplicaciones web solo podían interactuar con archivos a través de los cuadros de diálogo de carga (<input type="file">) y descarga (<a> con atributo download). Esto era suficiente para muchas tareas, pero limitaba severamente la capacidad de las PWAs para actuar como "aplicaciones de escritorio" completas. La File System Access API aborda estas limitaciones al proporcionar:

• Lectura y Escritura Directa: Capacidad de abrir y guardar archivos directamente en ubicaciones elegidas por el usuario.
• Persistencia Mejorada: Las aplicaciones pueden recordar el acceso a archivos o directorios, permitiendo sesiones de edición continuas sin re-seleccionar.
• Rendimiento: Manipulación de archivos localmente puede ser significativamente más rápida que depender de la red.
• Experiencia de Usuario: Una interacción más fluida y natural, similar a las aplicaciones nativas.
• Capacidades Offline: Manipular archivos incluso sin conexión a internet.

🛠️ Entendiendo los Conceptos Clave

Antes de sumergirnos en el código, es fundamental comprender los objetos y métodos principales de la File System Access API.

FileSystemFileHandle y FileSystemDirectoryHandle 📂

Estos son los pilares de la API. Representan referencias a archivos y directorios, respectivamente. No son los archivos o directorios en sí mismos, sino manejadores que te permiten interactuar con ellos.

• FileSystemFileHandle: Un objeto que te permite interactuar con un archivo en el sistema de archivos del usuario. Puedes usarlo para leer su contenido, escribir en él o cambiar su nombre.
• FileSystemDirectoryHandle: Un objeto que te permite interactuar con un directorio. Puedes enumerar sus contenidos, crear nuevos archivos o subdirectorios, o acceder a elementos específicos dentro de él.

Tipos de Permisos 🔐

La API maneja dos tipos de permisos principales:

• Lectura ('read'): Permite a la aplicación leer el contenido de un archivo o enumerar los contenidos de un directorio.
• Escritura ('readwrite'): Permite a la aplicación leer, escribir y modificar archivos, o crear/eliminar elementos en un directorio.

Los permisos son otorgados por el usuario a través de cuadros de diálogo estándar del navegador y pueden ser de dos tipos:

1. Temporal: El permiso dura mientras la pestaña o ventana está abierta. Si el usuario cierra y reabre la aplicación, deberá otorgar el permiso nuevamente.
2. Persistente: El permiso se mantiene entre sesiones, incluso si el usuario cierra la aplicación. Esto ocurre cuando el usuario explícitamente elige "Guardar" o "Abrir" en un cuadro de diálogo del sistema de archivos, o cuando el manejador se almacena en IndexedDB y se recupera posteriormente.

Métodos Principales ✨

🧑‍💻 Implementación: Abrir y Guardar un Archivo de Texto

Vamos a empezar con un ejemplo práctico: crear una PWA que permita abrir un archivo de texto, modificar su contenido y luego guardarlo en la misma ubicación o en una nueva.

1. Preparando el Entorno 🛠️

Necesitarás un archivo index.html, style.css y app.js (o main.js) para tu PWA, junto con un manifest.json y un service-worker.js básico. Para este tutorial, nos centraremos en app.js.

index.html (Esqueleto Básico):

<!DOCTYPE html>
<html lang="es">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Editor de Texto PWA</title>
    <link rel="stylesheet" href="style.css">
    <link rel="manifest" href="manifest.json">
</head>
<body>
    <header>
        <h1>Mi Editor PWA con File System Access</h1>
        <nav>
            <button id="openFileBtn">📂 Abrir Archivo</button>
            <button id="saveFileBtn">💾 Guardar Archivo</button>
            <button id="saveAsFileBtn">📝 Guardar Como...</button>
        </nav>
    </header>
    <main>
        <textarea id="editor" placeholder="Escribe aquí..."></textarea>
    </main>
    <script src="app.js"></script>
</body>
</html>

style.css (Estilos Mínimos):

body { font-family: sans-serif; margin: 0; padding: 0; background-color: #f0f2f5; display: flex; flex-direction: column; min-height: 100vh; }
header { background-color: #333; color: white; padding: 15px; display: flex; justify-content: space-between; align-items: center; }
h1 { margin: 0; font-size: 1.5em; }
nav button { background-color: #007bff; color: white; border: none; padding: 10px 15px; margin-left: 10px; border-radius: 5px; cursor: pointer; font-size: 1em; }
nav button:hover { background-color: #0056b3; }
main { flex-grow: 1; padding: 20px; display: flex; }
#editor { width: 100%; height: 100%; border: 1px solid #ccc; border-radius: 5px; padding: 15px; font-size: 1.1em; resize: none; box-sizing: border-box; }

2. Lógica en app.js 🧑‍💻

Aquí es donde implementaremos la interacción con la API de Acceso al Sistema de Archivos.

// app.js

const openFileBtn = document.getElementById('openFileBtn');
const saveFileBtn = document.getElementById('saveFileBtn');
const saveAsFileBtn = document.getElementById('saveAsFileBtn');
const editor = document.getElementById('editor');

let currentFileHandle = null; // Para almacenar el manejador del archivo actual

// --- Funciones principales de la API de Acceso al Sistema de Archivos ---

// 1. Abrir un archivo
async function openFile() {
    try {
        // Usa window.showOpenFilePicker() para abrir el selector de archivos
        const [handle] = await window.showOpenFilePicker({
            types: [
                {
                    description: 'Archivos de Texto',
                    accept: {
                        'text/plain': ['.txt'],
                    },
                },
            ],
            excludeAcceptAllOption: false,
            multiple: false,
        });

        currentFileHandle = handle; // Guarda el manejador del archivo abierto
        const file = await currentFileHandle.getFile(); // Obtiene el objeto File del manejador
        const contents = await file.text(); // Lee el contenido como texto
        editor.value = contents; // Muestra el contenido en el editor

        console.log('Archivo abierto:', file.name);
        updateTitle(file.name);

    } catch (error) {
        if (error.name === 'AbortError') {
            console.log('El usuario canceló la selección del archivo.');
        } else {
            console.error('Error al abrir el archivo:', error);
            alert('No se pudo abrir el archivo. Consulta la consola para más detalles.');
        }
    }
}

// 2. Guardar en el archivo actual (si existe), o como nuevo (si no)
async function saveFile() {
    if (currentFileHandle) {
        // Si ya hay un archivo abierto, guarda en ese mismo manejador
        await writeFile(currentFileHandle, editor.value);
        alert('Archivo guardado con éxito.');
    } else {
        // Si no hay archivo abierto, usa 'Guardar Como'
        await saveFileAs();
    }
}

// 3. Guardar como un nuevo archivo (o seleccionar una nueva ubicación)
async function saveFileAs() {
    try {
        // Usa window.showSaveFilePicker() para mostrar el cuadro de diálogo "Guardar Como"
        const handle = await window.showSaveFilePicker({
            types: [
                {
                    description: 'Archivos de Texto',
                    accept: {
                        'text/plain': ['.txt'],
                    },
                },
            ],
        });

        await writeFile(handle, editor.value);
        currentFileHandle = handle; // Actualiza el manejador del archivo actual
        const file = await currentFileHandle.getFile();
        updateTitle(file.name);
        console.log('Archivo guardado como:', file.name);
        alert('Archivo guardado con éxito.');

    } catch (error) {
        if (error.name === 'AbortError') {
            console.log('El usuario canceló el guardado del archivo.');
        } else {
            console.error('Error al guardar el archivo:', error);
            alert('No se pudo guardar el archivo. Consulta la consola para más detalles.');
        }
    }
}

// Función auxiliar para escribir contenido en un FileSystemFileHandle
async function writeFile(fileHandle, contents) {
    // Crea un objeto WritableStream para escribir en el archivo
    const writableStream = await fileHandle.createWritable();
    // Escribe el contenido en el stream
    await writableStream.write(contents);
    // Cierra el stream para guardar los cambios
    await writableStream.close();
}

// Función auxiliar para actualizar el título de la página
function updateTitle(fileName) {
    document.title = `Editor PWA - ${fileName}`;
}

// --- Event Listeners ---
openFileBtn.addEventListener('click', openFile);
saveFileBtn.addEventListener('click', saveFile);
saveAsFileBtn.addEventListener('click', saveFileAs);

// --- Registro del Service Worker (para que sea una PWA real) ---
if ('serviceWorker' in navigator) {
    window.addEventListener('load', () => {
        navigator.serviceWorker.register('/service-worker.js')
            .then(registration => {
                console.log('Service Worker registrado con éxito:', registration.scope);
            })
            .catch(error => {
                console.error('Fallo el registro del Service Worker:', error);
            });
    });
}

manifest.json (Ejemplo Básico):

{
  "name": "Editor de Texto PWA",
  "short_name": "Editor PWA",
  "description": "Un editor de texto simple con capacidades PWA y acceso al sistema de archivos.",
  "start_url": ".",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#333333",
  "icons": [
    {
      "src": "icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

service-worker.js (Ejemplo Mínimo):

// service-worker.js

const CACHE_NAME = 'pwa-editor-v1';
const urlsToCache = [
    '/',
    '/index.html',
    '/style.css',
    '/app.js',
    '/manifest.json',
    // Agrega aquí rutas a tus íconos y otros assets
];

self.addEventListener('install', event => {
    event.waitUntil(
        caches.open(CACHE_NAME)
            .then(cache => {
                console.log('Cache abierto');
                return cache.addAll(urlsToCache);
            })
    );
});

self.addEventListener('fetch', event => {
    event.respondWith(
        caches.match(event.request)
            .then(response => {
                if (response) {
                    return response; // Si está en caché, lo devuelve
                }
                return fetch(event.request); // Si no, va a la red
            })
    );
});

self.addEventListener('activate', event => {
    const cacheWhitelist = [CACHE_NAME];
    event.waitUntil(
        caches.keys().then(cacheNames => {
            return Promise.all(
                cacheNames.map(cacheName => {
                    if (cacheWhitelist.indexOf(cacheName) === -1) {
                        return caches.delete(cacheName); // Elimina caches antiguos
                    }
                })
            );
        })
    );
});

📁 Trabajando con Directorios: showDirectoryPicker()

La capacidad de interactuar con directorios es igualmente potente, permitiendo a las PWAs gestionar colecciones de archivos, como proyectos o galerías de imágenes. Aquí te mostramos cómo puedes usar showDirectoryPicker().

Enumerar Contenidos de un Directorio 🔍

// app.js (añadir a continuación del código anterior)

const openDirectoryBtn = document.createElement('button');
openDirectoryBtn.textContent = '📂 Abrir Carpeta';
document.querySelector('nav').appendChild(openDirectoryBtn);

let currentDirectoryHandle = null;

async function openDirectory() {
    try {
        const directoryHandle = await window.showDirectoryPicker();
        currentDirectoryHandle = directoryHandle;
        console.log('Directorio abierto:', directoryHandle.name);

        const filesInDirectory = document.createElement('ul');
        filesInDirectory.innerHTML = '<h3>Contenido de la carpeta:</h3>';
        for await (const entry of directoryHandle.values()) {
            const listItem = document.createElement('li');
            listItem.textContent = `${entry.kind === 'file' ? '📄' : '📁'} ${entry.name}`;
            filesInDirectory.appendChild(listItem);
        }

        // Un simple ejemplo para mostrar el contenido
        const main = document.querySelector('main');
        if (main.querySelector('ul')) {
            main.querySelector('ul').remove();
        }
        main.appendChild(filesInDirectory);

    } catch (error) {
        if (error.name === 'AbortError') {
            console.log('El usuario canceló la selección del directorio.');
        } else {
            console.error('Error al abrir el directorio:', error);
            alert('No se pudo abrir el directorio. Consulta la consola para más detalles.');
        }
    }
}

openDirectoryBtn.addEventListener('click', openDirectory);

Creando Archivos y Subdirectorios en una Carpeta ➕

Con un FileSystemDirectoryHandle, también puedes crear nuevos archivos o subdirectorios dentro de él, siempre que tengas permisos de escritura ('readwrite').

// app.js (añadir a continuación del código anterior)

const createNewFileBtn = document.createElement('button');
createNewFileBtn.textContent = '➕ Nuevo Archivo en Carpeta';
document.querySelector('nav').appendChild(createNewFileBtn);

async function createNewFileInDirectory() {
    if (!currentDirectoryHandle) {
        alert('Primero abre una carpeta.');
        return;
    }

    try {
        // Solicitar permisos de escritura si no los tenemos aún
        const permissionStatus = await currentDirectoryHandle.requestPermission({ mode: 'readwrite' });
        if (permissionStatus !== 'granted') {
            alert('Se requieren permisos de escritura para crear archivos.');
            return;
        }

        const fileName = prompt('Nombre del nuevo archivo (ej. mi-documento.txt):');
        if (!fileName) return;

        const newFileHandle = await currentDirectoryHandle.getFileHandle(fileName, { create: true });
        // Ahora puedes escribir en newFileHandle como lo harías con cualquier otro archivo
        await writeFile(newFileHandle, `Contenido inicial de ${fileName}`);
        alert(`Archivo '${fileName}' creado en '${currentDirectoryHandle.name}'.`);

        // Opcional: Volver a listar el contenido para ver el nuevo archivo
        openDirectory(); 

    } catch (error) {
        console.error('Error al crear el archivo en el directorio:', error);
        alert('No se pudo crear el archivo. Consulta la consola para más detalles.');
    }
}

createNewFileBtn.addEventListener('click', createNewFileInDirectory);

💾 Persistencia de Manejadores de Archivos y Directorios

Una de las características más potentes de la File System Access API es la capacidad de persistir los FileSystemFileHandle y FileSystemDirectoryHandle entre sesiones. Esto significa que un usuario no tiene que seleccionar el mismo archivo o directorio una y otra vez cada vez que vuelve a la PWA. Esto se logra almacenando los manejadores en IndexedDB.

Almacenar Manejadores en IndexedDB 🗄️

Cuando el usuario concede permiso a un manejador, puedes guardarlo en IndexedDB. La próxima vez que el usuario abra la aplicación, puedes intentar recuperar ese manejador y, si aún tiene permisos, usarlo directamente.

// app.js (añadir a continuación del código anterior)

const DB_NAME = 'fileSystemHandlesDB';
const DB_VERSION = 1;
const STORE_NAME = 'handles';

async function openDB() {
    return new Promise((resolve, reject) => {
        const request = indexedDB.open(DB_NAME, DB_VERSION);

        request.onupgradeneeded = (event) => {
            const db = event.target.result;
            db.createObjectStore(STORE_NAME);
        };

        request.onsuccess = (event) => {
            resolve(event.target.result);
        };

        request.onerror = (event) => {
            reject('Error al abrir IndexedDB:', event.target.error);
        };
    });
}

async function saveHandleToDB(key, handle) {
    const db = await openDB();
    const tx = db.transaction(STORE_NAME, 'readwrite');
    const store = tx.objectStore(STORE_NAME);
    await store.put(handle, key);
    await tx.complete;
    console.log(`Manejador '${key}' guardado en IndexedDB.`);
}

async function getHandleFromDB(key) {
    const db = await openDB();
    const tx = db.transaction(STORE_NAME, 'readonly');
    const store = tx.objectStore(STORE_NAME);
    const handle = await store.get(key);
    await tx.complete;
    console.log(`Manejador '${key}' recuperado de IndexedDB.`);
    return handle;
}

// Modificar las funciones openFile y saveFileAs para usar IndexedDB

// En openFile:
// currentFileHandle = handle;
// await saveHandleToDB('lastOpenedFile', handle); // Guardar el manejador

// En saveFileAs:
// currentFileHandle = handle;
// await saveHandleToDB('lastOpenedFile', handle); // Guardar el manejador

// Al cargar la PWA, intenta recuperar el último manejador
window.addEventListener('load', async () => {
    // ... (registro de service worker)

    const lastHandle = await getHandleFromDB('lastOpenedFile');
    if (lastHandle) {
        const permissionStatus = await lastHandle.queryPermission({ mode: 'readwrite' });
        if (permissionStatus === 'granted') {
            currentFileHandle = lastHandle;
            const file = await currentFileHandle.getFile();
            const contents = await file.text();
            editor.value = contents;
            updateTitle(file.name);
            console.log('Último archivo abierto recuperado y cargado.');
        } else {
            console.log('Permisos revocados o no persistentes para el último archivo.');
        }
    }
});

🌐 Consideraciones para PWAs y la File System Access API

La implementación de esta API en tus PWAs conlleva una serie de consideraciones importantes para garantizar una buena experiencia de usuario y seguridad.

Soporte de Navegadores 🚀

Actualmente, la File System Access API está bien soportada en navegadores basados en Chromium (Chrome, Edge, Opera, Samsung Internet) en escritorio. El soporte en otras plataformas y navegadores (Firefox, Safari) está en desarrollo o bajo consideración. Es crucial usar detección de características antes de intentar usar la API.

if ('showOpenFilePicker' in window) {
    // La API está disponible, puedes usarla
    console.log('File System Access API disponible.');
} else {
    // La API no está disponible, proporcionar una alternativa
    console.warn('File System Access API no disponible. Usando métodos de archivo tradicionales.');
    openFileBtn.disabled = true;
    saveFileBtn.disabled = true;
    saveAsFileBtn.disabled = true;
    // Implementar fallback para cargar/descargar archivos estándar si es necesario
}

Seguridad y Permisos 🔒

La seguridad es primordial. La API está diseñada con un modelo de permisos robusto:

• Siempre Iniciado por el Usuario: Ninguna PWA puede acceder al sistema de archivos sin una interacción explícita del usuario (un clic en un botón).
• Cuadros de Diálogo Nativos: Los selectores de archivos/directorios son los del sistema operativo, familiares para el usuario.
• Alcance Restringido: Los permisos son para archivos o directorios específicos, no para todo el sistema.
• Permisos de Escritura: Los permisos de escritura son más restrictivos y a menudo requieren una confirmación adicional o son temporales a menos que se use showSaveFilePicker().
• Transparencia: El navegador indica claramente qué sitio web está solicitando acceso a qué recursos.

Experiencia de Usuario (UX) ✅

• Feedback Visual: Proporciona feedback claro al usuario sobre si un archivo se ha abierto o guardado con éxito. Usa mensajes de éxito o error.
• Estado de la Aplicación: Si el usuario ha abierto un archivo, muestra su nombre en el título o en la interfaz.
• Manejo de Errores: Captura y maneja los errores, especialmente AbortError cuando el usuario cancela un selector.
• Fallbacks: Para navegadores que no soportan la API, proporciona una experiencia alternativa (por ejemplo, subir/descargar archivos a un servidor o usar IndexedDB para almacenamiento local simple).

Optimización de Archivos Grandes 📊

Para archivos muy grandes, evita cargar todo el contenido en memoria de una vez. La API permite trabajar con streams, lo que es ideal para procesar datos por partes. FileSystemWritableFileStream ya es un stream, y puedes leer archivos grandes con file.stream().

let result;
while (!(result = await reader.read()).done) {
    const chunk = result.value; // 'chunk' es un Uint8Array
    console.log(`Leído un chunk de ${chunk.length} bytes.`);
    // Procesa el chunk aquí, en lugar de cargar todo el archivo
}
console.log('Lectura de archivo grande completada.');

</details>

### Acceso a Directorios de Origen Privado de la PWA 📦

Además de interactuar con el sistema de archivos del usuario, la API también ofrece un concepto de **"origen privado"** (Origin Private File System). Este es un sistema de archivos virtual, aislado dentro del ámbito de tu origen web, al que tu PWA tiene acceso de escritura y lectura *sin permisos del usuario* una vez instalada. Es ideal para almacenar datos de la aplicación que no necesitan ser accesibles por el usuario fuera de la PWA.

<div class="timeline">
  <div class="timeline-item"><strong>Paso 1: Acceso a `navigator.storage.getDirectory()`</strong>: Obtén el manejador del directorio raíz privado.</div>
  <div class="timeline-item"><strong>Paso 2: Crear Archivos/Directorios</strong>: Usa `getDirectoryHandle()` y `getFileHandle()` con la opción `{ create: true }` para gestionar tus propios archivos.</div>
  <div class="timeline-item"><strong>Paso 3: Leer/Escribir Datos</strong>: Opera con los manejadores como lo harías con los archivos del sistema del usuario, pero sin solicitar permisos.</div>
</div>

```javascript
async function useOriginPrivateFS() {
    try {
        const root = await navigator.storage.getDirectory();
        console.log('Accedido al directorio raíz privado del origen:', root.name);

        const myFileHandle = await root.getFileHandle('config.json', { create: true });
        await writeFile(myFileHandle, '{"setting":"value"}');
        console.log('Archivo config.json creado en OPFS.');

        const file = await myFileHandle.getFile();
        const contents = await file.text();
        console.log('Contenido de config.json:', contents);

    } catch (error) {
        console.error('Error al usar Origin Private File System:', error);
    }
}

// Llama a esta función en algún momento, por ejemplo, al iniciar la aplicación
// useOriginPrivateFS();