OPFS: el sistema de archivos que el usuario nunca ve

Durante veinte años el navegador te ofreció cajas donde guardar cosas: un diccionario de cadenas, un almacén de objetos, una caché de respuestas HTTP. Nunca te ofreció lo que cualquier programa de escritorio da por sentado desde 1970 —un archivo con un offset, donde puedes reescribir el byte 8192 sin tocar los 8191 anteriores—. OPFS es exactamente eso: un sistema de archivos real, con su árbol de directorios, que aparece sin diálogo, sin ruta visible y sin que el usuario llegue a saber nunca que existe.

Dos puertas, el mismo tipo de manejador

El File System Standard del WHATWG define una jerarquía muy pequeña de objetos: FileSystemHandle, del que descienden FileSystemFileHandle y FileSystemDirectoryHandle. Un manejador no es una ruta ni un descriptor numérico: es una referencia opaca a una entrada del árbol, y todo lo que puedes hacer con un archivo pasa por tenerla.

Lo interesante es que hay dos formas distintas de conseguir manejadores del mismo tipo, y solo se diferencian en su procedencia:

flowchart TD
A[Tu codigo] --> B[showOpenFilePicker o showDirectoryPicker]
A --> C[navigator.storage.getDirectory]
B --> D[Dialogo del sistema y permiso revocable]
C --> E[Sin dialogo y sin gesto del usuario]
D --> F[Manejador sobre un archivo real del disco]
E --> G[Manejador sobre el arbol privado del origen]
F --> H[Misma interfaz: getFile y createWritable]
G --> H

// Puerta 1: la File System Access API. Exige gesto del usuario y permiso.
const [elegido] = await window.showOpenFilePicker();

// Puerta 2: OPFS. Ni gesto, ni diálogo, ni permiso.
const raiz = await navigator.storage.getDirectory();

raiz.kind;                                   // 'directory'
raiz.name;                                   // '' — la raíz no tiene nombre
elegido instanceof FileSystemFileHandle;     // true

A partir de aquí el código que lee y escribe es literalmente el mismo. La superficie completa cabe en una pantalla, y conviene verla junta desde el principio para calibrar cuánto tendrás que construir tú:

// FileSystemHandle — común a los dos tipos
handle.kind;                    // 'file' | 'directory'
handle.name;
await handle.isSameEntry(otro);

// FileSystemDirectoryHandle
await dir.getFileHandle(nombre, { create: true });
await dir.getDirectoryHandle(nombre, { create: true });
await dir.removeEntry(nombre, { recursive: true });
await dir.resolve(descendiente);
for await (const [nombre, h] of dir.entries()) { /* ... */ }

// FileSystemFileHandle
await file.getFile();           // leer
await file.createWritable();    // escribir

Eso es todo. No hay copiar, ni mover, ni renombrar, ni consultar metadatos sin abrir, ni buscar por patrón. Puedes escribir una capa de persistencia agnóstica que reciba un FileSystemDirectoryHandle y no sepa —ni le importe— si vino de un selector o de la raíz privada. Esa simetría es deliberada y es una de las mejores decisiones de diseño de la plataforma web reciente.

La asimetría está en todo lo demás.

Qué significa privado del origen

El origen es la tupla esquema más host más puerto. https://app.ejemplo.com y https://www.ejemplo.com son orígenes distintos, y por tanto tienen árboles distintos, sin ningún puente entre ellos: ni lectura, ni listado, ni prueba de existencia. No hay una raíz común más arriba desde la que fisgar.

// El mismo código, dos orígenes: dos árboles que jamás se cruzan.
const raiz = await navigator.storage.getDirectory();
await raiz.getFileHandle('marca.txt', { create: true });

for await (const nombre of raiz.keys()) console.log(nombre);
// en https://app.ejemplo.com  → ['marca.txt']
// en https://www.ejemplo.com  → []

OPFS vive dentro del subsistema de almacenamiento del navegador, junto a IndexedDB y Cache Storage, sujeto a la misma cuota y a las mismas políticas de borrado. No es un montaje del disco del usuario: es un sistema de archivos virtual que el navegador implementa como quiere. Chrome guarda las entradas en su directorio de perfil con nombres opacos, Safari y Firefox lo hacen de otra manera, y nada de eso es contrato.

De hecho ni siquiera está garantizado que exista un fichero real por cada entrada tuya. La especificación describe el comportamiento observable —un árbol, entradas con nombre, bytes con offset— y deja libre la representación: una implementación podría empaquetar entradas pequeñas, comprimirlas o guardarlas dentro de una base de datos interna, y seguiría siendo conforme. Lo único que puedes exigir es la semántica, nunca la forma.

Esa libertad tiene un efecto agradable poco conocido: como los nombres no tienen que sobrevivir al sistema de ficheros anfitrión, OPFS admite nombres que el sistema operativo rechazaría. Puedes llamar a una entrada aux, con o PRN en Windows, o usar caracteres que un sistema real prohíbe, sin que nada se rompa, porque el navegador ya está traduciendo por debajo.

Un modelo de permisos por ausencia

La File System Access API arrastra toda la maquinaria que cabe esperar de algo que toca los archivos personales: exige un gesto del usuario, abre un diálogo del sistema, concede permisos que se consultan con queryPermission() y se piden con requestPermission(), y esos permisos caducan al recargar la pestaña. Un manejador guardado en IndexedDB sobrevive a la recarga, pero vuelve sin permiso y hay que revalidarlo.

OPFS no tiene nada de eso. No hay diálogo, no hay gesto, no hay requestPermission(), y funciona igual desde el hilo principal, desde un Worker o desde un Service Worker, en el primer milisegundo de vida de la página.

// Detección de capacidad, antes de comprometer la arquitectura.
const hayOpfs = typeof navigator !== 'undefined'
  && navigator.storage
  && typeof navigator.storage.getDirectory === 'function';

if (!hayOpfs) {
  // Camino alternativo sobre IndexedDB, o degradar a solo memoria.
}

La pregunta razonable es por qué se considera aceptable que un origen escriba en el disco sin avisar. La respuesta es que el permiso protege un recurso ajeno, y aquí no hay ninguno: el sitio no puede leer nada que no haya escrito él mismo, ni enumerar lo de otros, ni siquiera comprobar si otro origen existe. Lo único que sí pertenece al usuario es el espacio libre del disco, y ese recurso no se gobierna con un diálogo —que nadie sabría contestar— sino con la cuota y el desalojo, que es el tema de la lección 5.

Qué habilita de verdad

Este nivel recorre el camino asíncrono completo: el árbol de directorios en la lección 2, la lectura y la escritura en la 3, la justificación frente a IndexedDB en la 4 y los límites en la 5. El camino síncrono —los manejadores de acceso que hacen posible SQLite y que solo existen dentro de un worker— es el nivel 10 entero.