La prueba de origen de la API de File System Observer

Thomas Steiner

La API de File System Access y la API de Origin Private File System permiten a los desarrolladores acceder a archivos y directorios en el dispositivo del usuario. El primero permite que los desarrolladores lean y escriban en el sistema de archivos normal visible para el usuario, y el segundo abre un sistema de archivos especial oculto para el usuario que es privado para el origen de cada sitio y que ofrece ciertas ventajas de rendimiento. En ambos casos, los desarrolladores interactúan con archivos y directorios a través de objetos FileSystemHandle, más concretamente, FileSystemFileHandle para archivos y FileSystemDirectoryHandle para directorios. Hasta ahora, para conocer los cambios en un archivo o directorio en cualquiera de los sistemas de archivos, se requería algún tipo de sondeo y comparación de la marca de tiempo lastModified o incluso el contenido del archivo en sí.

La API de File System Observer, en prueba de origen desde Chrome 129, cambia eso y permite que se alerte automáticamente a los desarrolladores cuando se producen cambios. En esta guía, se explica cómo funciona y cómo probar la función.

Casos de uso

Usa la API de File System Observer en las apps que necesiten recibir información sobre los posibles cambios en el sistema de archivos tan pronto como se produzcan.

  • Entornos de desarrollo integrados (IDE) basados en la Web que muestran una representación del árbol del sistema de archivos de un proyecto
  • Apps que sincronizan los cambios del sistema de archivos con un servidor Por ejemplo, un archivo de base de datos SQLite.
  • Apps que necesitan notificar al subproceso principal sobre los cambios en el sistema de archivos desde un subproceso de trabajador o desde otra pestaña
  • Apps que observan un directorio de recursos, por ejemplo, para optimizar imágenes automáticamente
  • Experiencias que se benefician de la recarga en caliente, como las presentaciones de diapositivas basadas en HTML, en las que un cambio de archivo activa una recarga.

Cómo usar la API de File System Observer

Detección de características

Para ver si se admite la API de File System Observer, ejecuta una prueba de funciones como en el siguiente ejemplo.

if ('FileSystemObserver' in self) {
  // The File System Observer API is supported.
}

Inicializa un observador del sistema de archivos

Inicializa un observador del sistema de archivos llamando a new FileSystemObserver() y proporcionándole una función callback como argumento.

const observer = new FileSystemObserver(callback);

Comienza a observar un archivo o directorio

Para comenzar a observar un archivo o directorio, llama al método asíncrono observe() de la instancia FileSystemObserver. Proporciona a este método el FileSystemHandle del archivo o directorio seleccionado como argumento. Cuando observas un directorio, hay un argumento options opcional que te permite elegir si deseas recibir información sobre los cambios en el directorio de forma recursiva (es decir, para el directorio en sí y todos los subdirectorios y archivos contenidos). La opción predeterminada es observar solo el directorio y los archivos que contiene directamente.

// Observe a file.
await observer.observe(fileHandle);
// Observe a directory.
await observer.observe(directoryHandle);
// Observe a directory recursively.
await observer.observe(directoryHandle, {recursive: true});

La función de devolución de llamada

Cuando se producen cambios en el sistema de archivos, se llama a una función de devolución de llamada con el cambio en el sistema de archivos records y el propio observer como argumentos. Puedes usar el argumento observer para, por ejemplo, desconectar el observador (consulta Cómo dejar de observar el sistema de archivos) cuando se borren todos los archivos que te interesan.

const callback = (records, observer) => {
  for (const record of records) {
    console.log('Change detected', record);
  }
};

Registro de cambios en el sistema de archivos

Cada registro de cambio del sistema de archivos tiene la siguiente estructura. Todos los campos son de solo lectura.

  • root (un FileSystemHandle): Es el identificador que se pasa a la función FileSystemObserver.observe().
  • changedHandle (un FileSystemHandle): Es el identificador afectado por el cambio en el sistema de archivos. Este campo será null para los eventos de tipo "errored", "unknown" y "disappeared". Para ver qué archivo o directorio desapareció, usa relativePathComponents.
  • relativePathComponents (un Array): Es la ruta de acceso del changedHandle en relación con el root.
  • type (un String): Es el tipo de cambio. Los siguientes tipos son posibles:
    • "appeared": Se creó el archivo o directorio, o se movió a root.
    • "disappeared": Se borró el archivo o directorio, o se lo movió fuera de root.
    • "modified": Se modificó el archivo o directorio.
    • "moved": El archivo o directorio se movió dentro de root.
    • "unknown": Indica que se omitieron cero o más eventos. Los desarrolladores deben sondear el directorio observado en respuesta a esto.
    • "errored": La observación ya no es válida. En este caso, es posible que desees dejar de observar el sistema de archivos. Este valor también se enviará cuando se alcance el límite máximo de observaciones por origen. Este límite depende del sistema operativo y no se conoce de antemano. Si esto sucede, es posible que el sitio decida volver a intentarlo, aunque no hay garantía de que el sistema operativo haya liberado suficientes recursos. Otro caso en el que se enviará este valor es cuando se borre o mueva el identificador observado (es decir, la raíz de la observación). En este caso, primero se envía el evento "disappeared" y, luego, un evento "errored", lo que indica que la observación ya no es válida. Por último, este evento se envía cuando se quita el permiso para el directorio o el identificador de archivo.
  • relativePathMovedFrom (un Array, opcional): Es la ubicación anterior de un identificador que se movió. Solo está disponible cuando type es "moved".

Cómo dejar de observar un archivo o directorio

Para dejar de observar un FileSystemHandle, llama al método unobserve() y pásale el identificador como argumento.

observer.unobserve(fileHandle);

Deja de observar el sistema de archivos

Para dejar de observar el sistema de archivos, desconecta la instancia de FileSystemObserver de la siguiente manera.

observer.disconnect();

Prueba la API

Para probar la API de File System Observer de forma local, configura la marca #file-system-observer en about:flags. Para probar la API con usuarios reales, regístrate en la prueba de origen y sigue las instrucciones de la guía Pruebas de origen de Chrome. La prueba de origen se ejecutará desde Chrome 129 (11 de septiembre de 2024) hasta Chrome 134 (26 de febrero de 2025).

Demostración

Puedes ver la API de File System Observer en acción en la demostración incorporada. Consulta el código fuente. La demostración crea, borra o modifica archivos de forma aleatoria en un directorio observado y registra su actividad en la parte superior de la ventana de la app. Luego, registra los cambios a medida que ocurren en la parte inferior de la ventana de la app. Si lees esto en un navegador que no admite la API de File System Observer, consulta una captura de pantalla de la demostración.

Comentarios

Si tienes comentarios sobre la forma de la API de File System Observer, comenta el problema #123 en el repositorio de WHATWG/fs.

Agradecimientos

Daseul Lee, Nathan Memmott, Etienne Noël y Rachel Andrew revisaron este documento.