Leer y escribir: el flujo de escritura y el objeto de fichero

Escribir en OPFS por el camino asíncrono no modifica el fichero: crea una copia de trabajo invisible, acumula ahí tus cambios y la publica de golpe cuando cierras. Esa indirección te regala atomicidad gratis —nadie verá jamás un fichero a medio escribir— y te cobra un precio que crece con el tamaño del fichero hasta hacerse insoportable. Entender exactamente dónde está la frontera es lo que separa usar OPFS de sufrirlo.

Escribir: la copia de trabajo

createWritable() devuelve un FileSystemWritableFileStream, que es un flujo de escritura estándar con tres comandos extra. Mientras esté abierto, el fichero visible no cambia ni un byte: todo va a una copia intermedia que el navegador mantiene aparte.

flowchart LR
A[createWritable] --> B[Copia de trabajo oculta]
B --> C[write y seek y truncate]
C --> D[close]
D --> E[Reemplazo atomico del fichero]
C --> F[abort]
F --> G[Se descarta todo y el fichero queda intacto]

const raiz = await navigator.storage.getDirectory();
const h = await raiz.getFileHandle('nota.txt', { create: true });

const w = await h.createWritable();
await w.write('hola mundo');                            // escribe y avanza
await w.write({ type: 'seek', position: 0 });           // reposiciona
await w.write({ type: 'write', position: 5, data: 'MUNDO' });
await w.truncate(10);                                   // recorta o rellena
await w.close();                                        // aquí se publica

write() acepta texto, un Blob, un ArrayBuffer, una vista tipada o un objeto de comando con type, position y data. La forma con posición explícita es la que te da acceso aleatorio real, y es la que usarías para tocar la cabecera de un formato binario sin reescribir el resto.

Ahora el detalle que arruina más datos en producción: por defecto la copia de trabajo empieza vacía. Si abres un fichero de un megabyte, escribes cuatro bytes y cierras, el fichero mide cuatro bytes. No has parcheado nada: lo has sustituido.

// Destructivo: el contenido anterior desaparece al cerrar.
const w1 = await h.createWritable();
await w1.write('x');
await w1.close();                       // el fichero mide 1 byte

// Preservando: la copia parte del contenido actual.
const w2 = await h.createWritable({ keepExistingData: true });
await w2.write({ type: 'write', position: 1_000_000, data: 'y' });
await w2.close();

También hay exclusión mutua. Mientras un manejador de escritura esté abierto sobre una entrada de OPFS, otro intento de abrirlo falla con NoModificationAllowedError. Es un cerrojo real que atraviesa pestañas y workers del mismo origen, y por tanto es tu primera línea de defensa contra dos escritores concurrentes, aunque no sustituye a una coordinación explícita con Web Locks.

Leer: el objeto de fichero es perezoso

getFile() devuelve un File, que es un Blob con nombre y fecha de modificación. La llamada no lee nada: te entrega una referencia con metadatos y la lectura ocurre cuando pides los bytes.

const archivo = await h.getFile();
archivo.size;           // bytes, sin haber leído ninguno
archivo.lastModified;   // milisegundos desde epoch

await archivo.text();          // AHORA sí: todo a memoria
await archivo.arrayBuffer();   // ídem, y como copia binaria

// Rango perezoso: slice no materializa nada.
const cabecera = await archivo.slice(0, 100).arrayBuffer();

slice() es la herramienta central para trabajar con ficheros grandes: devuelve otro Blob que sigue siendo una referencia a un rango, y solo el arrayBuffer() final trae bytes a memoria. Con eso puedes leer la página 5000 de un fichero de dos gigabytes tocando cuatro kilobytes.

Un objeto de fichero es además una instantánea. Si otra pestaña reescribe la entrada después de que lo obtuvieras, tu referencia queda obsoleta y leerla puede fallar:

const viejo = await h.getFile();
// ... otro escritor cierra un manejador de escritura sobre h ...
await viejo.text();   // puede lanzar NotReadableError

La regla práctica es no guardar objetos de fichero: guarda el manejador, que es estable, y pide un fichero nuevo justo antes de cada lectura. Un objeto de fichero es un préstamo con fecha de caducidad desconocida; un manejador es una referencia.

Esa misma caducidad explica una asimetría que sorprende al principio: el manejador no te dice el tamaño, ni la fecha de modificación, ni si la entrada sigue existiendo. Todo eso vive en el objeto de fichero, es decir, en la instantánea, precisamente porque son datos que pueden dejar de ser ciertos en cualquier momento. La API prefiere obligarte a pedirlos otra vez antes que dejarte creer que tienes un stat cacheado y correcto.

Datos grandes: flujos en las dos direcciones

Para tamaños que no caben en memoria, ninguna de las dos puntas debe materializarse. Un Blob produce un flujo de lectura y un manejador de escritura es un flujo de escritura, así que se conectan directamente:

// Descargar a disco sin pasar por memoria, con contrapresión incluida.
const respuesta = await fetch('/modelo.bin');
const destino = await raiz.getFileHandle('modelo.bin', { create: true });
await respuesta.body.pipeTo(await destino.createWritable());

// Leer por trozos: nunca hay más de un fragmento vivo.
const lector = (await h.getFile()).stream().getReader();
let leidos = 0;
while (true) {
  const { done, value } = await lector.read();
  if (done) break;
  leidos += value.byteLength;   // value es un Uint8Array
}

El techo del camino asíncrono