El árbol: crear, recorrer y borrar

La API del árbol de OPFS cabe en cinco métodos y no tiene ni una sola función que acepte una ruta. No hay mkdir -p, no hay stat, no hay rename, no hay glob. Esa pobreza aparente no es un descuido de la especificación: es la consecuencia de haber elegido manejadores en vez de rutas, y en cuanto entiendes qué es un manejador, la ausencia de todo lo demás pasa de carencia a decisión.

La raíz y sus dos verbos

Todo empieza en navigator.storage.getDirectory(), que devuelve una promesa del FileSystemDirectoryHandle raíz. Un directorio expone exactamente dos formas de bajar: pedir un subdirectorio o pedir un fichero. Crear no es un verbo aparte, sino una opción de la búsqueda.

const raiz = await navigator.storage.getDirectory();

const datos = await raiz.getDirectoryHandle('datos', { create: true });
const wal   = await datos.getFileHandle('journal.wal', { create: true });

// Sin la opción de creación, buscar algo que no existe es un error.
try {
  await raiz.getFileHandle('fantasma.bin');
} catch (e) {
  e.name;   // 'NotFoundError'
}

flowchart TD
R[raiz sin nombre] --> D1[datos]
R --> D2[adjuntos]
D1 --> F1[db.sqlite]
D1 --> F2[journal.wal]
D2 --> D3[2026]
D3 --> F3[imagen-001.bin]

El detalle que más código rompe la primera vez es que los nombres son nombres, no rutas. Pasar un separador es un error de tipo, no una navegación implícita, y lo mismo ocurre con los nombres reservados del directorio actual y del padre:

await raiz.getFileHandle('datos/db.sqlite');   // TypeError
await raiz.getDirectoryHandle('..');           // TypeError

Si quieres el equivalente de crear una ruta profunda de una vez, lo escribes tú. Son seis líneas y conviene tenerlas en el proyecto desde el primer día:

async function asegurarRuta(raiz, ruta) {
  let dir = raiz;
  for (const segmento of ruta.split('/').filter(Boolean)) {
    dir = await dir.getDirectoryHandle(segmento, { create: true });
  }
  return dir;
}

const destino = await asegurarRuta(raiz, 'adjuntos/2026/agosto');

Recorrer: iteración asíncrona

Un directorio es un iterable asíncrono. Tienes keys() para los nombres, values() para los manejadores y entries() para ambos, y siempre se consumen con for await. No hay ninguna llamada que te devuelva el listado completo de golpe, porque no hay ninguna garantía de que quepa en memoria.

for await (const [nombre, manejador] of datos.entries()) {
  console.log(manejador.kind, nombre);   // 'file' | 'directory'
}

El recorrido recursivo, que necesitarás para calcular el tamaño ocupado o para exportar, sale natural como generador asíncrono:

async function* recorrer(dir, prefijo = '') {
  for await (const [nombre, manejador] of dir.entries()) {
    const ruta = `${prefijo}/${nombre}`;
    if (manejador.kind === 'file') {
      const f = await manejador.getFile();
      yield { ruta, bytes: f.size, modificado: f.lastModified };
    } else {
      yield* recorrer(manejador, ruta);
    }
  }
}

let total = 0;
for await (const entrada of recorrer(raiz)) {
  total += entrada.bytes;
  console.log(entrada.ruta, entrada.bytes);
}

Fíjate en que el tamaño de un fichero no está en su manejador: hay que pedir el objeto de fichero con getFile() para conocerlo. Un manejador no cachea metadatos, y esa es otra pista de que no es un stat, sino una referencia.

Borrar, y la identidad de los manejadores

El borrado se pide al directorio padre, nunca a la entrada, y un directorio con contenido no se va salvo que lo digas explícitamente:

await datos.removeEntry('journal.wal');
await raiz.removeEntry('adjuntos');                    // InvalidModificationError
await raiz.removeEntry('adjuntos', { recursive: true }); // ahora sí

Y aquí llega la propiedad que más desconcierta: dos manejadores del mismo fichero no son el mismo objeto. Cada llamada crea uno nuevo, así que la comparación por identidad siempre miente. Para preguntar si dos manejadores apuntan a la misma entrada hay un método dedicado, y para saber dónde está uno respecto de otro hay otro:

const a = await datos.getFileHandle('db.sqlite', { create: true });
const b = await datos.getFileHandle('db.sqlite');

a === b;                    // false
await a.isSameEntry(b);     // true
await raiz.resolve(a);      // ['datos', 'db.sqlite']
await datos.resolve(a);     // ['db.sqlite']

resolve() devuelve null si el manejador no desciende del directorio consultado, y es la única forma legítima de reconstruir algo parecido a una ruta: siempre relativa a un ancestro que ya tienes, nunca absoluta.

// Delegar el subárbol a un worker: la capacidad viaja con el mensaje.
const propietario = new Worker('/almacen.js', { type: 'module' });
propietario.postMessage({ tipo: 'adoptar', dir: datos });